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PREFACE 



The RBM User's Guide explains how to use some of the more basic and commonly required features of the RBM 
operating system- It is to be used with, but does not supplant, the RBM/RT, BP Reference Manual, 90 10 37.^ The 
writing style is informal, and technical terminology is avoided wherever possible for the benefit of the new RBM user. 

The primary intent of the User's Guide is to assist new users in getting their first programs on the RBM system with a 
minimum of study. No attempt has been made to provide comprehensive examples for utilizing every feature in the 
RBM system. Your understanding of this manual will be improved if you are already partly familiar with the contents 
of the RBM Reference Manual, although this is not strictly necessary. One assumption that has been made however, 
is that you have at least a basic understanding of one of the programming languages that operate under RBM (i-e. , 
ANS FORTRAN IV or Extended Symbol). 

The User's Guide illustrates the necessary interface between your program and the operating system's services through 
a series of job examples and short discussions of specific applications. The examples generally present the simplest 
case for each application. Once these are thoroughly understood, the use of more sophisticated options, their re- 
lationships to one another, and the techniques for implementing them will be more readily apparent. 

An effort has been made to organize the text so that experienced real-time programmers can directly access topics 
of immediate interest. A study of the Table of Contents should enable you to go directly to such relevant items and 
skip through other material already familiar to you. 

In reading the User's Guide, you will probably notice that some definitions and several other items of information 
are repeated in several places. This repetition is intentional. Its purpose is to reenforce your understanding of cer- 
tain basic terms and concepts that will make the learning of more complex facets of the system an easier task. 

A full understanding of the material in this manual will not, in itself, make you an expert in utilizing all the capa- 
bilities of the RBM system. Further study of the RBM Reference Manual and some experience in the writing, 
checkout, and running of programs will be necessary. When going on to an in-depth study of the RBM Reference 
Manual and related manuals, there is a simple technique that may be used to help you learn new features of the sys- 
tem. The technique is not to study each unfamiliar feature with respect to its relationship to other parts of the sys- 
tem (whose significance may also be slightly hazy), but rather to key each item directly to some real or imaginary 
program. You can do this by asking yourself the following questions, as appropriate: 

1. Why would I want it for my program and what will it do? 

2. How do I use it? 

3. If I can't use it, why not? 

4. Is it a service I must request for myself, or does the system provide it automatically? 

5. What are its possible side effects? 

6. Is there another, perhaps better, way that I can accomplish the same thing? 

Such a program-oriented approach to learning new features is less confusing, and will eventually lead to a rec- 
ognition of the relationships between system components (much of the material in the RBM User's Guide was prepared 
by using this same study technique). 



The User's Guide contains a number of references to appropriate sections of the RBM/RT, BP Reference Man- 
ual, 90 10 37. For purposes of brevity, the title of that manual has been shortened to "RBM Reference Manual" 
in all such references. 



VI 



If you are unfamiliar with the RBM system and have not had an opportunity to attend formal or informal training 
classes, it may be useful to review the available RBM documentation. By placing each manual in its proper con- 
text in terms of relevance to your own programming efforts, such a review may suggest general guidelines for further 
study and the priorities of such study. 

• RBM/iRT, BP Reference Manual, 90 10 37; This manual is addressed to all personnel within an RBM instal- 
lation. It is the primary reference for all resources and services provided by the RBM system and gives 
detailed descriptions of each feature with explicit instructions for utilizing them. Since FORTRAN users 
commonly call Monitor services indirectly through the FORTRAN library, the areas of immediate interest 
to the FORTRAN programmer will be the sections dealing with the background processors, with special em- 
phasis on their control command structure: Monitor, RAD Editor, Overlay Loader, and Utility Processor. 
The sections on operator communication (unsolicited key-ins) and the Public Library will also be per- 
tinent. Assembly language users, in addition to the items above, will require a knowledge of the Monitor 
service routines and I/O sections of the manual, since these users request Monitor services directly in their 
code. Real-time programmers, both assembly language and FORTRAN users, will need to study the real- 
time programming section (assembly language users should give some emphasis to the Task Control Block 
subsection). The section on System Generation will be of primary interest to the installation's system pro- 
grammers. The Standard Object Language appendix will usually be of interest only to those engaged in 
writing their own language processors and to systems programmers. The RBM Reference Manual is not in- 
tended to be a tutorial text. It is a feature oriented and logically organized approach to the system, as 
opposed to the User Guide's job oriented approach. 

• RBM/OPS Reference Manual, 90 15 55: This manual is addressed to programmers/operators working at the 
console. It is basically a digest of operations and diagnostic features abstracted from the RBM Reference 
Manual and is organized in alphabetical sequences, rather than logical, for fast reference when corrective 
action is required while running a job. The RBM/OPS Manual confines itself to control command formats, 
operator key-ins, various diagnostic and warning messages, and some peripheral device considerations and 
data switch settings. 

• RBM/System Technical Manual, 90 11 53: This manual is addressed to system programmers and analysts 
who are concerned with the internal structure of the RBM system for maintenance purposes. It is to be used 
in conjunction with the system listings supplied to each RBM installation, and the manual is essentially a 
"rood map" through the RBM listings. Generally speaking, this manual has limited value or interest to ap- 
plications programmers. 

• Sigma 2 or 3 Computer Reference Manuals, 90 09 64 and 90 15 92; These manuals (whichever is pertinent) 
are addressed to all RBM users, but have particular relevance to real-time users because of the descriptions 
of the hardware interrupt structure. Of special importance to assembly language users are the sections on 
the machine instruction set and I/O, since these users generally are "closer to the machine "than FORTRAN 
users. 

The programming language manuals listed in "Related Publications" Include Information on the language processor 
Interface with RBM. (FORTRAN/kBM Interface will be found In the appropriate FORTRAN Operations Manual.) 

System programmers, real-time programmers, or any others who may be involved In heavy file management or spe- 
cialized hardware peripheral considerations should consult the XDS PAL Manual, supplied to each Installation, for 
a description of the appropriate peripheral reference manuals. It should be noted that the PAL Manual also contains 
descriptions of available software packages that were generated by other members of the User's Group. 



1. THE RBM OPERATING SYSTEM 



Before discussing ways for your program to utilize basic RBM services it is necessary to come to a common understanding 
of certain concepts, terms, and processes within the RBM context. The first of these is the operating system 
itself. 

An operating system consists of all the software used at a local facility to perform the services for which the instal- 
lation was designed. The software includes the Real-Time Batch Monitor, language processors (assemblers and 
compilers), service processors, and user programs, all closely integrated for a given number of applications. 

No two operating systems are completely alike, because the user-created programs that form the user's extension of 
the operating system and the processors chosen from the manufacturers list of software modules are selected to fit 
unique requirements of the local facility. These requirements frequently change, and the system is correspondingly 
enlarged or otherwise modified. 

These factors are generally found in all operating systems, but there are other characteristics that make RBM unique. 

REAL-TIME BATCH MONITOR SYSTEM 

A real-time system such as RBM has event-driven scheduling for ail real-time operations. That is, certain external 
events occurring outside the immediate environment of the installation, such as various processes in an automated 
factory or biomedical diagnostic lab, determine which real-time computer operation is taking place at any given 
moment in time. The sequence of these real-time operations is not under the immediate control of a computer 
operator or programmer. 

Furthermore, although a number of outside events can be taking place simultaneously, each event has a priority of 
importance in relation to all others, and this priority level determines which event gets service from the system first. 
Each real-time event produces a signal that is connected to a hardware interrupt. The interrupt Is the connecting 
link between the external event and the real-time task that responds to it. 



Under control of a real-time program, the computer can be set to respond to external events in many ways that 
do not involve scanning or decision making by the CPU. For example, when one interrupt level becomes 
ACTIVE, two or three higher, related levels might be DISABLED (postponed) long enough for the active level 
to complete a portion of its work before the higher levels could become active. Yet any incoming signals 
could be remembered. Further, a higher level that was ARMED and ENABLED could become ACTIVE immedi- 
ately upon receiving an external signal. 



This leads into one of the most important and distinguishing features of a true real-time operating system such 
as RBM: unlike other forms of operating systems that may offer some real-time capability as a secondary fea- 
ture, RBM guarantees that its ability to provide extremely fast responses to interrupts will not be degraded by 
outside interference. That Is, within the predictable limits of the hardware interrupt priority system and cer- 
tain structural considerations of the real-time software (program segmentation), RBM absolutely protects a cur- 
rently active real-time event from any slowing of response time (within 100 microseconds) by the actions of a 
lower-priority real-time process, a background process, or even Inadvertent human Interference such as hitting 
a Control Panel INTERRUPT switch. Further, the Monitor never Interjects Itself between real-time processes 
and their Interrupts, but remains passively ready to respond immediately to calls for service from real-time ex- 
ternal events within the self-imposed time limit stated above. 



Some body of user-designed code (called a task) is associated with each Interrupt level, and the RBM system is 
organized around the concept of tasks and programs. The most fundemental unit of software associated with an 
interrupt is the real-time task. 

The RBM Operating System 



REAL-TIME TASK 

A task is a body of code (and data) associated with one and only one hardware priority interrupt. This task is 
executed only if its corresponding interrupt level becomes ACTIVE. The task executes at the priority of its level 
and may be interrupted by a higher priority task. When completed, the higher level task will exit to the next lower 
waiting task. It does this by restoring any registers that have been modified, by restoring system pointers and status 
values to their previous conditions and by executing an instruction to exit from the current active level. These func- 
tions are performed either by a Monitor Service Routine or by the task itself. 

Tasks may be triggered by other tasks or by external events. For example, a very high priority task may be con- 
nected ( via an interrupt level) toon external signal. When the signal triggers the interrupt, the high priority task 
may be used to collect real-time data. The task may then terminate itself, triggering (under program control) a 
lower priority level task to process the data. The lower level task can continue processing at a less critical time 
when all intermediate levels are inactive. This procedure prevents loss of valuable data due to conflicting demands 
on computer time, yet enables the computer to be used as fully as possible for the most critical operations. It should 
be noted that it is never necessary for a task to know specifically which task it is interrupting or which task inter- 
rupted it. Note also that there is a distinction between real-time tasks and foreground programs. 

FOREGROUND PROGRAMS 

A real-time program Is a collection of one or more related tasks and common data loaded and controlled as a unit. 
This collection of tasks may have (but need not have) contiguous interrupt levels in hardware priority sequence. 
Such a program is identifiable by name, so that it may be loaded into core memory or released from memory on re- 
quest. A foreground program could consist of a single task, and the triggering of its interrupt would set off a series 
of processes in serial sequence. 

It Is possible to have foreground programs that are not controlled by external events but which nevertheless execute 
in foreground memory (and are connected to hardware interrupt levels) with all the protection privileges and use of 
dedicated I/O devices that real-time tasks have. Such programs may be loaded and released by the computer oper- 
ator by other foreground tasks, or may be loaded from the background job stack. They may be operated periodically 
from a real-time clock, I/O end-actions, etc. 

A foreground program may be called in and initialized by any of the following: 

Another foreground task 

Computer operator (unsolicited key-in) 

Background job stream 



Execution of the tasks connected to interrupts may be caused by any of the following processes: 
External interrupt 
Real-time clock 
Computer operator (unsolicited key-in) 



There are three possible types of foreground programs in RBM and they are classified according to the manner and 
location in which they are installed in foreground memory. Foreground memory is divided into two areas: resident 
and nonresident. 

1. A resident foreground program is automatically loaded Into Its fixed area (absolute location) in resident 
foreground memory every time the system is booted In. 

2 Real-Time Task/Foreground Programs 



2. A semlresident foreground program is explicitly called from secondary storage (RAD or disk pack) into its 
portion of resident foreground memory for execution. The explicit call is made either by a resident fore- 
ground program or operator key-in. It is the responsibility of the caller to ensure that the required memory 
space is really available and not already occupied, since the program is unconditionally loaded. 

3. A nonresident foreground program is also explicitly called by another foreground program or operator key- 
in from secondary memory but normally is loaded into the nonresident portion of foreground memory for 
execution. The space thus occupied is considered "active" and the program is fully protected by the 
Monitor from the background. If the nonresident space is already occupied when the call is made, the re- 
quest is queued. "^ 

Note that foreground programs, regardless of type or function, can only execute (e.g., perform read/write and 
compute operations in the foreground area. Compilations or assemblies can never take place in the foreground mem- 
ory area. Therefore, before any foreground programs and tasks can be executed, they must first have been created 
by background jobs. 

BACKGROUND JOBS 

A job is the basic independent process performed In the background area of memory. Each job is independent of any 
other job, and consists of one or more directly or Indirectly related job steps. A job step Is the execution of a single 
language processor program, service processor program, or user program within a job. The program for each step is 
brought in for execution by a processor command that identifies the program. Jobs can call for Extended Symbol 
assemblies or FORTRAN compilations; that is, they can translate your source (symbolic) deck Into a binary format 
called the relocatable object module, and then call in a service processor called the Overlay Loader to form the 
executable version of your program termed the absolute load module or program file. 

Background jobs are frequently referred to as batch jobs, which means that RBM permits you to load a series of jobs 
for sequential processing (see "Job Stream Summary" below and Chapters 2 and 3 for definition) or build a job stack 
of several unrelated jobs. Naturally, all Inputs that follow a given processor command within a batch must be writ- 
ten in the same language; that is, all must be written in FORTRAN or all in Extended Symbol, etc. Additionally, 
the parameters specified on the processor command will apply to every input module that follows it within the job 
step. The primary purpose in batching jobs is to reduce Idle time between jobs and to increase throughput speed. 

All background jobs, whether they are to become real-time programs or not, are loaded, assembled or compiled, 
and checked out in the same way. The only difference is that jobs intended for the foreground must be given per- 
mission to be loaded into protected foreground memory through operator FG key-Ins and options on some control 
commands before the executable versions are loaded in a protected foreground area. 

As implied above, some background jobs never become foreground programs. Once they have been processed into 
executable form, they are executed in the background memory area as background programs. Background programs 
are identified by name, (filename), the same as foreground programs. Background programs must execute in user 
mode and must perform all I/O through Monitor service routines, as opposed to foreground programs that execute in 
master mode and can either elect to use Monitor service routines or perform their own I/O. 

In this explanation of job processing, we hove implied that various services are performed by the system to aid your 
programming efforts, and we have alluded to "foreground" and "background" memory without defining them fully. 
Further discussion of foreground/background programs requires that we now define these as well as other terms. 

THE MONITOR 

The Monitor is the supervisor or executive part of the system that controls, coordinates, and provides services for 
both real-time and background programs. For background processing, the communications link between you 
and the Monitor is through a subprocessor called the Job Control Processor (JCP). The JCP reads, interprets, and 



In RBM, "queuing" refers to a list of entries maintained by the Monitor that identifies items waiting for service or 
attention. The following terms are sometimes interchangeably used with queuing: scheduling, sequencing, ordering, 
or dispatching. 

Background Jobs/The Monitor 3 



RESPONSE TIME 

Response Hme is the total time it takes for a task to begin executing meaningful instructions in response to some 
external signal. If a program must be brought into core, response time is the total time required to access the RAD, 
bring the root into core, initialize, and then respond to external interrupt(s). The amount of delay in response time 
that can be tolerated must be determined for each individual real-time program (and sometimes each task)within the 
system. However, many real-time applications at a given facility do not need response time as rapid as that avail- 
able with resident programs, and of course, response time is not a factor in background programs. 

The following section summarizes preceding material and presents additional information that is necessary before 
going on to the examples in Chapter 2 or 3. 

JOB STREAM SUMMARY 

Sigma RBM provides two levels of services for computer users: real-time (foreground) services and batch (back- 
ground) services. The sequence of foreground programs is controlled by external interrupts, interval timers, a call 
by another foreground task, or the computer operator. Most operating system services are called in via system func- 
tion calls within the program, with certain other services being implicitly provided. 

Batch programs are processed serially in the order submitted. There are four primary subprocessors (often called 
service processors) to assist the Monitor in providing service to the background job stream: 

Job Control Processor 

Overlay Loader 

RAD Editor 

Utility Processor 

To make use of these background service processors, each job submitted must conform to the general requirements of 
the operating system and the specific requirements of the service processor being utilized. 

The portion of the operating system that responds to control commands preceded by an exclamation mark (!) and 
performs and coordinates many other system functions in the background is the Job Control Processor. The terms 
"JCP commands" and "Monitor commands" are frequently used interchangeably. The JCP accepts control command 
input from a specific input device designated as the Control Command Device (referred to in this manual as the 
"CC" device). This device is commonly a card reader, although other media may be used instead of cards (the use 
of a RAD or magnetic tape as the "CC" device generally is not recommended because they are less flexible). 

In a typical batch operation, several jobs are combined into a single "batch stream" although each fob retains 
its identify through its preceding !JOB (or IJOBC) control command. The entire job stream is terminated when 
the JCP interprets a IFIN control command that informs the Monitor that no more jobs are to be processed in 
the current batch stream. 

In addition to the IFIN control command terminating the batch stream and the I JOB control command preceding each 
job, other Monitor control commands may be used within a job to request various services. For example, a ! LIMIT 
control command may be used if the user wants to limit the processing time or other system resources expended. 
Should the job exceed the time limits defined on the ! LIMIT command, it would be aborted. 

There are many control commands that can be used in a job, with one of the most generally useful being the 
{ASSIGN command. An {ASSIGN command may be used to direct the flow of I/O to or from a specified 
peripheral device or RAD file. {ASSIGN commands enable the user to write a program containing symbolic 
reference to "logical" I/O devices rather than to "physical" devices by assigning a device-file name to an 
operational label (logical device name), RAD file, or physical device. This allows selection of a particular 
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physical device to be deferred until the job deck is prepared, and also permits any logical device to be reassigned 
at certain points v/ithin job processing. 



In addition to controlling the assignment of a logical device, an lASSIGN command may be used to control a variety 
of I/O parameters for that device. For example, on lASSIGN command may specify that a particular logical device 
is to read information from a specified RAD file. When the user's program is executed during a subsequent step 
within the job, the Monitor searches its Master File Directory for the specified file, and makes that file available 
whenever data is to be read via the assigned device. The lASSIGN commands remain in effect until the next IJOB 
or IJOBC command is encountered. 

A background job is a collection of one or more job steps. A job step is all the control commands required for the 
setup and execution of a single processor or user program within a job. These job steps can be one of the service 
processors, a standard language processor such as Extended Symbol orANS FORTRAN IV, or a user-designed program. 

Each processor, whether a service or language processor, is called for execution by means of a "processor" control 
command. A processor control command begins with an exclamation mark followed by a name identifying the re- 
quested processor; e.g., 1 FORTRAN or IXSYMBOL. Such commands may also contain parameters pertaining to the 
execution of the program; the exact form depending on which processor is being called. Data decks usually follow a 
processor command, although data may be input from a RAD file or other media. 

Binary output from a language processor may be produced on punched cards, magnetic or paper tape, or a RADfile. 
Such output is always in Sigma Standard Object Language format and must be translated (link edited) into execut- 
able format by either the Absolute Loader or Overlay Loader before it can be executed by the computer. The Abso- 
lute Loader is called via an lABS command, and is principally used to place the Overlay Loader on the RAD at 
System Load (SYS LOAD) time. While the Absolute Loader can also be used for placing user programs on the RAD, 
this is generally not recommended, and there are a number of restrictions in using it for this purpose (the Absolute 
Loader is described in the Sigma RBM Reference Manual under the lABS command). 

The Overlay Loader is called via an lOLOADcontrol command, and is a much more powerful and versatile processor 
for user program purposes. Throughout the rest of this manual, the term "Loader" always refers to the Overlay 
Loader unless otherwise stated. 

The lOLOAD command may specify parameters related to the program elements to be loaded, the type of program, 
(foreground or background) being constructed, and other optional parameters. If no special options are needed, the 
command lOLOAD is sufficient. The name of the operational label used for the output generated by the Loader is 
always "OV", which is assigned by default to a special file located in the System Data area of the RAD, and is 
termed "RBMOV". The OV operational label is used to rewrite on this file. The output of the Loader is called a 
program file (load module), which is a RAD file containing a core image of the executable program. 

The program in RBMOV (sometimes referred to as the "OV file") file is called for execution via an IXEQ 
command. Note that there is no protection for the program in the OV file. However, this file is not altered 
by the Monitor, and unless changed by the background job stream, may remain intact between jobs. 



Object modules may be linked by the Loader to form an "overlay" program structure. The logical structure of 
an overlay program is defined for the Loader by means of l$ROOT and 1$SEG Loader subcommands that must 
follow the lOLOAD command. Segments are identified by segment numbers and are defined by 1$SEG com- 
mands for use by MrSEGLD service routine calls coded into the user's program. Segment is always the root. 

After a background program has been processed by the Loader, it may be brought into core for execution by 
means of an IXEQ or Iname command. Foreground programs can be loaded by an IXEQ command or by a 
Monitor service routine call in another foreground task. Use of an IXEQ control command to load foreground 
programs must be preceded by an operator FG key-in. 
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File allocation, management, and manipulation is provided by calling in the RAD Editor service processor via a 
IRADEDIT control command. The IRADEDIT command itself requires no parameters; after the RAD Editor is called 
in, it reads subcommands that have a number sign (*) in column 2 and following an exclamation character in 
column 1. These subcommands identify the functions to be performed, such as FCOPY, {^TRUNCATE, I'^^DELETE, 
etc., and each contains user-defined parameters that specify the RAD areas and files to be processed. 

Further file manipulation, such as file and record editing functions, copying files from one non-RAD device to an- 
other non-RAD device, etc., is provided by calling the Utility processor through a lUTILITY control command that 
also defines the type of Utility function to be used. Each Utility function has its own set of unique control sub- 
commands that further define a given operation to be performed. 

The operating system is capable of handling foreground tasks and background batch jobs concurrently because of the 
allocation of core into distinct foreground and background areas. All programs eventually intended for real-time 
applications are first assembled or compiled, processed by the Loader, and checked out through the background job 
stream. The programs are then loaded into their assigned files in the Foreground Programs area of the RAD. There- 
after, all new or modified foreground programs are first assembled or compiled in the background job stream in ex- 
actly the same fashion as any other batch job, and memory is allocated as required. 

Now that basic orientation for the RBM system has been provided, some job examples for compiling or assembling 
and loading through the background can be considered. If you plan to write most of your program in FORTRAN you 
should go on to the next chapter. If you plan to write programs in assembly language, you should skip to Chapter 3. 
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2. HOW TO COMPILE AND LOAD FORTRAN JOBS 



Xerox Basic FORTRAN, Xerox Basic FORTRAN IV, and Xerox ANS FORTRAN IV are the standard FORTRAN 
compilers currently available to Sigma 2/3 RBM users. In a typical foreground/background environment, FORTRAN 
users may range from engineers or other technical personnel who only occasionally write programs and have little in- 
terest in the internal functions of the RBM system, to real-time programmers whose knowledge of the software and 
hardware must be extensive. The discussion and examples that follow in this and other chapters are in increasing 
order of complexity that reflects this user range. 

The examples in this chapter use the ANS FORTRAN IV specification options on the ! FORTRAN processor card. 
Except for this major difference, all examples are equally valid for users of the other two compilers unless otherwise 
noted. ANS FORTRAN IV will process programs written for Basic FORTRAN and Basic FORTRAN IV. 

COMPILATION WITH SOURCE LISTING 

Figure 1 shows a FORTRAN job deck with the minimum control commands required to obtain a compilation of a 
source program and a source listing output to the line printer. The UOB command informs the Monitor that a new 
job is being input. Optionally, the UOB command could also contain an account number and user-defined name; 
e.g., UOB 12345, FORTSAMP if job account was being used at the local facility. 

Since binary output is not usually desired for an initial compilation and you will want to "desk check" the source 
listing before producing an object deck, the two ! ASSIGN cards are used to suppress binary output to the BO 
(usually a card punch) and GO devices. If BO and GO were not assigned to 0, a request for binary output would 
be assumed by default. 

The [FORTRAN card specifies a source listing (always defaulted) and the SQ option specifies that the compiler is to 
perform a sequence check of the source deck. Use of the SQ option is recommended for all initial compilations. 

The !EOD card indicates that no further FORTRAN source statements are to be compiled and allows the compiler to 
exit to the Job Control Processor (JCP). 



Z 



!FIN 



!EOD 



Source deck 




! FORTRAN SQ 



lASSIGN GO = 



lASSIGN BO=0 



UOB 



Figure 1. Compile with Source Listing and Suppressed Binary Output 
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The !FIN card informs the system that the job is completed and no other jobs are forthcoming. Should the job be 
one of a series in a "batch", the source decks would be followed by an !EOD card for each deck instead of !FIN 
until the final deck was input. This example is the simplest case of an ANS FORTRAN compilation under RBM. 

COMPILE MAIN PROGRAM WITH SUBPROGRAMS 

Compilation of a FORTRAN program with included subprograms poses no problems in terms of RBM interface- The 
single lASSIGN card shown in Figure 2 suppresses binary output to the GO device but binary output to the BO de- 
vide will be produced in this case. The compiler will produce a source listing on the line printer. The system does 
not require any control commands between the subprogram modules. 



!FIN 



!EOD 



FORTRAN Subprogram 



FORTRAN Subprogram 




X 



z 



FORTRAN Subprogram 



Main FORTRAN program 



^ 



O 



! FORTRAN SO 



IASSIGN GO=0 



!JOB 



Figure 2. FORTRAN Compilation with Subprograms, Binary Output to BO Device, and Source and Object 
Listing to LO Device 

EXECUTE OBJECT MODULE FROM CARD INPUT 

After a source program has been successfully compiled into a binary object version that is free of obvious logical or 
coding errors, it is ready to be reloaded into the computer for execution. The example in Figure 3 shows the deck 
structure for loading a FORTRAN - produced binary object deck. Note that in this example we are assuming that 
the BI operational label is assigned to the card reader device at the local installation; if this was not the case, BI 
would have to be temporarily reassigned to this device via an lASSIGN command. 
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Compile Main Program with Subprograms/Execute Object Module from Card Input 



Optional 




!FIN 



!EOD 



Data deck 




Object Module 




!$ROOT ,,BI,1 



lOLOAD 



UOB 



J/ 



J/ 



Figure 3. Object Program Input from Card Reader for Executfon 

The lOLOAD card calls in the Overlay Loader, and the BI and 1 parameters on the Loader !$ROOT card informs the 
Loader that it is to read one object module (binary deck) from the cord reader, translate this into the load module 
(executable program or program file) and write this executable program into the RBMOV file. The RBMOV file is 
the default output file for the Loader and is located on the RAD. The default OV file will be reused the next time 
a program is loaded. The use of the lOLOAD card without parameters implies default of all options. Therefore, this 
will be a root only, background program with COMMON size token from the object module (see the Overlay Loader 
chapter of the RBM Reference Manual for discussion of other options). The double comma on the !$ROOTcard tells 
the Loader that the default cases are to be used for the "temp" and "exioc" options. 

The !XEQ card causes the core image copy of the executable program to be loaded into core from RBMOV to 
process the data. 

COMPILE AND EXECUTE FORTRAN PROGRAM 

when your source program has been checked out to the point where any remaining coding errors are likely to be 
minor or the program is very simple, it is often useful to compile, load, and execute the program as one job. This 
procedure is commonly known as a "load-and-go" operation, and saves both computer time and unnecessary hand- 
ling of the job. 



In the load-and-go example illustrated in Figure 4, the I ATTEND card immediately following the UOB card 
inhibits the Monitor Abort routine so that the system will go into a wait state instead of aborting the program 
in case any remaining program error is encountered. This will enable you to attempt corrective action at con- 
sole while the program is still in memory, and is generally recommended for personally attended load-and-go 
jobs. 



Since there are no commands preceding the ! FORTRAN processor card, binary output will be written to both 
the BO and GO devices. The GO "device" is the RBMGO file on the RAD, and is the file from which 
the Overlay Loader will read its input. A source listing will be printed. The JOLOAD card calls the Over- 
lay Loader, and the GO option on the !$ROOT card informs the Loader that it is to read one object module 
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!FIN 



!EOD 



Data deck 



!XEQ 



!PMD ,ALL 




z: 



!EOD 



!$ROOT ,,GOJ 



!$ML 



lOLOAD 



!EOD 



Source deck 




! FORTRAN SQ,LO 



lATTEND 



!JOB 



Figure 4. FORTRAN Load and Go Job 

from the GO file, form the load module, and write it into the RBMOV file for subsequent loading into core for 
execution. The l$ROOT card also specifies that the "temp" and "exioc" default cases (double comma) are to 
be used. 

The !$ML card informs the Loader that a Long map is to be output (an example and explanation of a load map is 
given in Chapter 6, "How to Build An Overlay Program"). 

The IPMD card provides for a core dump for further diagnosis if corrective action at the console is unsuccessful. As- 
suming lATTEND was present, the !PMD card will cause a post-mortem dump to be output if you terminate a 
console recovery attempt with an X key-in (operator abort). Since ALL is specified, all of background mem- 
ory and the CPU registers will be dumped in case of an abort for any reason. Generally, use of a !PMD com- 
mand is advisable for load-and-go jobs regardless of the presence or absence of an lATTEND card. The IPMD 
command is effective only for the job step following its appearance. 

The !XEQ card calls the load module into core and gives control to the program for execution. 

Figure 5 illustrates the job flow of a typical load-and-go job. 
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FORTRAN Load 
and Go Job. 


P 


CPU 




Compiler 




RAD 






GO File (defaulO 



CPU ' 



Overlay Loader 




OVFile (default) 



CPU " 



User Program 



Figure 5. Load and Go Sequence 
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COMPILE, LOAD, AND GO FROM PERMANENT GO FILE 

In the last example, we made the statement that the contents of the RBMGO file (the default GO file) is temporary 
and will be destroyed the next time a program is assembled or compiled. In some cases, it may be desirable to save 
the compiler output. In cases where you may be modifying or patching a program and do not wish to recompile every 
time, the compiler output file can be saved by defining your own GO file on the RAD (i.e. , in the UD area). 

Creating a user-defined file involves two control commands: the RAD Editor l*ADD card and the ! ASSIGN card. 
The Editor l*ADD card is covered in more detail in the chapter "How To Create and Manipulate Files". 

In the example in Figure 6, the I PAUSE KEYIN SY, S card is used to remove Monitor protection of previously defined 
RAD areas, and it functions in a similar manner to the FG key-in except that It permits access to protected RADareas 
instead of foreground core memory. 



!FIN 



!EOD 



Data deck 



^ 



IXEQ 



!PMD ,ALL 



lEOD 



!$ROOT ,,GO,1 



[OLOAD 



z: 



lEOD 



Source deck 




! FORTRAN 



[ASSIGN GO=FORGO,UD 



!EOD 



1#ADD UD,FORGO,4,120,B 



IRADEDIT 



! PAUSE KEYIN SY,S 



[ATTEND 



[JOB 



Figure 6. Compile, Load, and Go from User-Defined GO File 
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The !*ADD card following the IRADEDIT card informs the Editor that a new entry is to be added to the UD area, 
the name of the user-defined file is FORGO, and the file size is four records. The record must be 120 bytes to 
accommodate the Standard Object Language, and the file format should be blocked sequential access (B) for 
space economy. 

The lASSIGN command temporarily assigns the GO operational label to file FORGO (for this one job only) in the 
UD area of the RAD. 

The [FORTRAN card specifies that a source listing is requested, a binary object deck is to be produced, and the Re- 
locatable Object Module (ROM) is to be written to the GO operational label (which is reassigned to file FORGO). 
Identical ROMS are output on both BO and GO. 

The Overlay Loader is called in (lOLOAD) and translates the ROM defined by the !$ROOT and (GO) into a load 
module and writes it in the RBMOV file (by default) for subsequent loading and execution. The double comma on 
the !$ROOT card specifies the default cose for the "temp" and "exioc" parameters. Note that although the number 
of modules is specified (1), the "1" does not actually have to be specified in this case, since the !EOD on the GO 
file would terminate reading of the module. 

BO instead of GO could have been assigned to file FORGO if a copy of the ROM was not desired from some selected 
device media. The choice is up to you, but there is a rule about assigning BO to a user file that should be 
remembered: 

• The record size specified on the !*ADD command must be 120 bytes (60 words per record) and an EOF 
should be written by the user (IWEOF BO) to properly indicate end of data in the file. The compiler 
does not write an EOF to the BO operational label. 

The Overlay Loader requires that all of its input object modules have 120-byte records and will abort the job if this 
is not so. Since the compiler does write an EOF to the GO operational label, no IWEOF command is necessary in 
the example; a file mark is written automatically at the end of the object module. 

COMPILE, LOAD, AND GO FROM PERMANENT OV FILE 

In the previous example, a program was compiled and the object module was written into a user -defined permanent 
GO file, but the Loader wrote the load module (executable program or program file) onto the RBMOV file for exe- 
cution. Like RBMGO, the RBMOV file contents are considered temporary and may be altered from one job to an- 
other. Using the OV file is a useful procedure for programs not completely checked out or subject to frequent 
updating. However, once a program is completely debugged, you con define your own permanent OV file. The 
program can then be loaded into core for execution repeatedly, without the necessity of recompiling or recreation of 
the load module by the Overlay Loader. 

The method for creating your own permanent OV file is quite similar to creating a permanent GO file, and again 
involves use of the lASSIGN command and the RAD Editor !*ADD command. 

In the example in Figure 7, the IRADEDIT card calls in the RAD Editor and the l^'^ADD card informs the Editor that 
a new entry is to be added to UP area. The name of the file is to be USEROV and there are four records within the 
file (filesize). The double comma specifies that the default record size is to be used and the format is to be random 
access (R). The file has write protection from everything except background programs (B). 

The [FORTRAN card specifies a source and object listing, sequence check, a binary object deck, and a copy of 
the object module to be written into the RBMGO file. 

The lASSIGN command assigns the OV operational label to file USEROV (for this one job only) in the UP area 
of the RAD. 
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!FIN 



ZIL 



!EOD 



Data Deck 




!XEQ 



!PMD ,ALL 



!EOD 



!$ROOT ,,Q>0 



lOLOAD 



[ASSIGN OV4JSEROV,UP 



z: 



!EOD 



Source Deck 



<> 



! FORTRAN SQ,LO 



UOB 



!EOD 



!#ADDUP,USEROVA/R/B 



IRADEDIT 



! PAUSE KEYIN SY,S 



'ATTEND 



UOB 



J/ 



Figure 7. Compile, Load, and Go from Permanent OV File 



The Overlay Loader translates the object module defined b/ the l$ROOT command into a load module and 
writes it in the USEROV file for subsequent execution. Future execution may be either by use of {ASSIGN 
OV = USEROV, UP end !XEQ cards, or the processor call ! USEROV. You have created a permanent user program 
named USEROV. 



Of course, there is nothing to prevent you from combining the creation of permanent GO and OV files into 
one job. This would merely involve adding the {ASSIGN and Editor {*ADD cards from the previous perma- 
nent GO file examples. 
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COMPILE AND EXECUTE IN FOREGROUND AREA 

An example of loading a FORTRAN job from the background job stream that is to be executed in the nonresident 
foreground area of memory is illustrated in Figure 8. The deck structure for such jobs is identical to other load- 
and-go [obs except that the operator must key-in FG,S to access foreground memory, and the foreground option (F) 
must be specified on the lOLOAD card (the default option is B for background). 



!FIN 



lEOD 



zz 



Data deck 



!XEQ 



!PMD ,ALL 



! PAUSE KEYIN FG,S 



!EOD 



!$ML 




l$ROOT ,,GO 



lOLOAD ,F,,,X 



lEOD 



ZZI 



Source deck 




I FORTRAN SQ,DB 



lATTEND 



!JOB 



Figure 8. Compile, Load, and Execute in Foreground Area 

All access to protected memory from the background job stream must be preceded by an FG key-in. Failure to do 
so is a foreground write protection violation and aborts the job unless an 1 ATTEND card is present. If [ATTEND 
is present and the [PAUSE KEY-IN FG,S card is accidently excluded, the Monitor will go into a wait state. The 
FG key-in must then be input and the command that caused the protection violation must be repeated. 

The first comma (preceding "F") on the lOLOAD card informs the Loader by default that only a root segment is 
to be loaded; the "F" identifies the load module as a foreground task; the triple comma specifies that the step 
mode and Debug options are not being used. The X parameter requests the Loader to abort the job if a severity 
level greater than zero is encountered during the load process. 
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The double comma on the !$RO0T card informs the Loader that the default temp stack size (80 cells) is to be 
used and that the default beginning location for the load module is to be KrNFFWA (nonresident foreground first 
word address) in the nonresident area of foreground memory. The GO option specifies that the Loader is to read 
the single ROM (1) from the RBMGO file and write the load module into the RBMOV file by default. 



The l$ML card causes the Loader to output a Long map when the load module is written into RBMOV. 



The .'PAUSE KEYIN FG,S card causes the system to go into a wait state so that the operator can perform the 
necessary FG,S combined key-in. This directs the Monitor to permit access to protected memory and continue 
processing. 



The !XEQ command causes the load module on OV to be loaded into nonresident foreground memory for exe- 
cution, beginning at location KrNFFWA. 



HOW TO USE 026 SOURCE AND DATA DECKS 

The RBM system expects all card images for source and data to be in the 029 character set. However, it is 
sometimes necessary or desirable to run FORTRAN jobs that were originally punched in the 026 character set 
format. 



RBM has SYSGEN input parameter options called BR4 (026 card input), BP3 (026 card punch output), and B7 
(7-track BCD magnetic tape) that will process I/O in BCD format instead of EBCDIC. If any or all of these 
required options are not already assigned to user-selected device file numbers at your local installation, it will 
be necessary to re-SYSGEN or perform a SYSGEN update before they can be used. See the subheading "In- 
put Parameters" in the System Generation chapter of the RBM Reference Manual. 



Figure 9 shows a complete FORTRAN job example with all input in 026 format, including main source program 
and subprograms on cards and the input data (to be read on FORTRAN device unit number F:112) on 7-track 
magnetic tape. The example assumes that a prior SYSGEN has assigned BR4 to device file number (DFN) 11 
and that B7 has been assigned to DFN 12. 



The presence of the ! ATTEND and IPMD cards are suggested for diagnostic and corrective action when sub- 
mitting a job that may be unfamiliar to the programmer submitting the job. 



The first lASSIGN card assigns the SI (source input) device to DFN 11 to read the source program and 
subprograms. 



The ! PAUSE command outputs the message on the card and then causes the Monitor to go into a wait state so 
that the operator can mount the 7-track tape containing the 026 input data to be processed. 



The next lASSIGN card assigns the FORTRAN device unit number (F:n2) to DFN 12 to read in the data at 
execution time. 



18 How to Use 026 Source and Data Decks 



!FIN 



EBCDIC (029) 
card codes 



EBCDIC (029) 
card codes 



!XEQ 



!PMD ,ALL 



[ASSIGN F:n2=12 (B7 DFN) 



! PAUSE MOUNT BCD DATA TAPE 



!EOD 



!$ROOT ,,GO 



(029) 



BCD (026) 
card codes 




lOLOAD 



!EOD 



User Subprogram (026 Code) 



User Subprogram (026 Code) 



Main Source Program (026 Code) 



! FORTRAN SO 



lASSIGN SI=11 (BR4 DFN) 



"ATTEND 



!JOB 





Figure 9. Job Sefup with 026 Source and Data 
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3. HOW TO ASSEMBLE AND LOAO EXTENOED SYMBOL JOBS 



Xerox Extended Symbol is the standard assembler available to RBM users. The information and examples in this 
chapter deal with the basic interface between RBM and your symbolic programs or updates; other and more com- 
plex material is given in the chapters concerning the Standard Procedure (S2) File, assembly language and FORTRAN 
routine interface, and real -time procedures. 

EXTENDED SYMBOL ASSEMBLIES 

Figure 10 shows an Extended Symbol job deck with the minimum control commands required to obtain an assembly 
listing output to the line printer. The UOB command informs the system that a new job is being input. Optionally, 
the iJOB command may also contain a name and account number (e.g., UOB SAMPl, 12345). 



I FIN 



lEOD 



Symbolic deck 




IXSYMBOL LO 



IJOB 



Figure 10. Assemble Single Program with Listed Output to LO Device 



The IXSYMBOL card following the IJOB card informs the JCP that control is to be transferred to the assembler 
and LO specifies that an assembly listing is to be output (normally to line printer). The BO parameter is not speci- 
fied because you will usually wish to "desk check" an initial assembly before producing an object deck. 

Since in this program example we do not wish to use all the default options available (BO,GO,and LO), the desired 
option (LO) is specified. The only output will be the assembly listing. 

The !EOD card must be present, to terminate execution of the assembler, before the !FIN card is encountered 
or the job will be aborted. The IFIN card informs the system that the job is completed and no other jobs are 
forthcoming. 



ASSEMBLE. LOAD AND 60 



When your source (symbolic) program has been "desk checked" to the point where any remaining errors are likely to 
be minor or nonexistent, it is often useful to assemble, load, and execute the resulting program file (load module)as 
one job. Such a job is commonly known as a "load-and-go" operation and saves both computer time and unneces- 
sary handling of the job. 
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In the load-and-go example illustrated in Figure 11, the IXSYMBOL card specified by default that listing output 
is to be transmitted to the LO device, that binary output is to be produced (BO), and that the object program producec 
from the assembly is to be written on the RBMGO file, from which it is later read by the Overlay Loader as input. 



!FIN 



!XEQ 



!PMD 



!EOD 



!$ROOT ,,GO,l 



z: 



lOLOAD 



!EOD 



Source deck 




IXSYMBOL 



lATTEND 



!JOB 



Figure 11. Assemble, Load, and GO 

The lOLOAD card calls in the Overlay Loader, and GO option on the !$ROOT card directs the Loader to read the 
object module from the GO file, translate this into the load module (executable program or program file) and load it 
onto the RBMOV file. The OV file contents are also temporary and may be destroyed if another load module is 
loaded into the file. 

The double comma on the !$ROOT card tells the Loader that the default cases are to be used for the "temp" 
and "exioc" options and the program will be executed in the background. The "1" following the GO parameter 
informs the Loader that only one object module is to be loaded. 



The !PMD card applies only to the job step following it, and provides added information for future diagnosis 
if corrective action at the console proves unsuccessful. Assuming lATTEND was present, the IPMD card will 
cause a post-mortem dump to be output if you terminate the console recovery attempt with an "X" key-in (op- 
erator abort). If the "U" option is specified, an unconditional dump will be output regardless of whether or not 
the program is aborted; if "U " is absent the dump will only be output if an abort (for any reason) takes place. 
If "ALL" is present, all background plus the CPU registers are dumped. Up to six pairs of "to" and "from" 
locations can be specified for selective dumping. If no options ore specified on the !PMD card, only the CPU 
registers will be dumped (these registers are always dumped regardless of any specified limits). Generally, use 
of the !PMD command is advisable for load-and-go jobs regardless of the presence or absence of an lATTEND 
card. The lATTEND card inhibits the Monitor abort routine and will cause the Monitor to go into a wait 
state instead of aborting a job so that corrective action can be attempted at the console. 

Since the IPMD card in the example does not contain any optional parameters, it will cause dumping of the CPU 
registers (only) if the program is aborted for any reason. 
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The !XEQ card causes the core image copy of the executable program located on OV to be loaded into 
background core and executed. 

LOAD AND GO FROM PERMANENT GO FILE 

It is sometimes desirable to save the assembler output. In cases where you may be modifying or patching a program 
every time it is loaded, the assembler output can be saved by defining your own file in the UD area (for instance). 

Creating a user-defined GO file involves use of two control commands not previously discussed: the RAD Editor 
!^ADD command and the I ASSIGN command. The Editor {"^ADD command is covered in the chapter "How To Cre- 
ate and Manipulate Files". 

In the example in Figure 12 the PAUSE KEYIN SY,S card is used as a check to remove Monitor protection of pre- 
viously defined RAD areas. SY is the RAD file analog of the FG key-in used for accessing foreground core memory. 

The I^ADD card following the IRADEDIT card informs the Editor that a new entry is to be added to the UD area, the 
name of the user-defined file is to be GOUSER, and the filesize is four records. The record size must be 120 bytes 
to accommodate the Standard Object Language, and the file format should be blocked sequential access (B) for 
space economy. 



z: 



!XEQ 



lEOD 



!$ROOT ,,GO,l 



lOLOAD 



lEOD 



Source deck 




IXSYMBOL 



{ASSIGN GO=GOUSER,UD 



lEOD 

|#ADD UD,GOUSER,4,120,B 



IRADEDIT 



{PAUSE KEYIN SY,S 



[ATTEND 



IJOB 



Figure 12. Load and Go from User-Defined GO File 
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The ! ASSIGN command temporarily assigns the GO operational label to file GOUSER (for this one [ob only) in 
the UD area of the RAD. 

The IXSYMBGL card specifies by default that a listing is desired (LO), binary output is to be produced on some 
peripheral device (normally a card punch), and the Relocatable Object Module (ROM) is to be written to the GO 
operational label which is reassigned to file GOUSER for this job. Identical ROMs will be written on both BO 
and GO. 

The Overlay Loader is called in (lOLOAD) and translates the ROM defined by the l$ROOT card (GO) into a load 
module and writes it in the RBMOV file by default for subsequent loading and execution. The double comma on the 
!$ROOT command specifies the default case for the "temp" and "exioc" parameters. Note that although the num- 
ber of modules is specified (1), the "1" does not actually have to be specified in this case, since the lEOD on the 
GO file would terminate reading of the module. 

BO instead of GO could have been assigned to file GOUSER if a copy of the ROM was not desired from some sel- 
ected device media. The choice is up to you, but there is a rule about assigning BO to a user file that should be 
remembered: 

• The record size specified on the l"^ADD command must be 120 bytes (60 words per record) and an EOFshould 
be written by .the user(!WEOF BO) to properly indicate end of data in the file. The assembler does not 
write EOF to the BO operational label. 

The Overlay Loader requires that all input object modules have 120-byte records and will abort the job if this is 
not so. Since the assembler does write an EOF to the GO operational label, no IWEOF command is necessary; a 
file mark is written automatically at the end of the object module. 

MODIFY AN ASSEMBLY IN A PERMANENT GO FILE 

Now that you have an assembled program located in a permanent file, it can be updated or modified without going 
through a reassembly. Using the GOUSER file from the previous example, the deck structure in Figure 13 wouldadd 
the patches and cause execution of the modified program. 



z: 



IXEQ 



lEOD 



Patch cards (1$MD. . .) 




!$ROOT ,,GO,l 



lOLOAD 



lASSIGN GO=GOUSER,UD 



(JOB 



Figure 13. Assembly Update from Permanent GO File 
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ASSEMBLE, LOAD, AND GO FROM PERMANENT OV FILE 

In the two previous examples a program was assembled and the object module was written into a user-defined 
permanent file, but the Loader wrote the load module (executable program or program file) onto the RBMOV file for 
execution. Like RBMGO, the RBMOV file's contents are frequently altered from one {ob to another- Using the 
RBMOV file is a useful procedure for programs not completely checked out or subject to frequent updating- How- 
ever, once a program is completely debugged, you can define your own permanent file. The program can then be 
loaded into core for execution repeatedly, without the necessity of reassembly or recreation of the load module by 
the Overlay Loader. 

The method for creating your own permanent file is quite similar to creating a permanent GO file, and again in- 
volves use of the RAD Editor !*ADD command and the {ASSIGN command. 

In the example in Figure 14, the IRADEDIT card calls in the RAD Editor and the I^ADD card informs the Editor 
that a new entry is to be added to the UP area; the name of the file is to be USEROV, and there are four records 
within the file (filesize). The double comma specifies that the default record size is to be used and the format is to 
be random access (R). The file has write protection from everything except background programs (B). 



^ 



!XEQ 



!EOD 



!$ROOT ,,GO,1 



lOLOAD 



lASSIGN OV=USEROV,UP 



!EOD 



deck 




IXSYMBOL LO,GO 



!JOB 



!EOD 



!'^ADDUP,USEROV,4,,R,B 



IRADEDIT 



! PAUSE KEYIN SY,S 



lATTEND 



IJOB 



Figure 14. Assemble, Load, and Go from Permanent OV File 
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The IXSYMBOL card specifies that listed output is to be produced (LO) and the object program is to be written on 
the RBMGO file (GO). 

The ! ASSIGN command assigns the OV operational label to file USEROV (for this one job only) In the UP 
area of the RAD. 

The Overlay Loader translates the object module, defined by the !$ROOT command, into a load module and writes 
it in the USEROV file for subsequent execution. Future execution may be either by use of lASSIGN OV=USEROV, 
UP and !XEQ commands, or the processor {name call lUSEROV. You have created a permanent user program named 
USEROV. 

Of course, there is nothing to prevent you from combining the creation of permanent GO and OV files into one job. 
This would merely involve adding the lASSIGN and Editor !*ADD cards from the previous permanent GO file 
examples. 

ASSEMBLE IN BATCH MODE 

A "batch" assembly is a series of successive assemblies performed with a single IXSYMBOL command. Batching of- 
fers processing and easier loading for the operator. There are three rules about batch assemblies that should be 
remembered: 

• The assignments and options on the single IXSYMBOL card apply to £jj_ assemblies within the batch 
stream. 

• Batch mode must be specified on the IXSYMBOL command via the BA option only if lEOD cards are used 
to separate the decks; otherwise, BA need not be specified. 

• The last job in a batch must be terminated by double !EOD cards if the BA option is specified. 

The example illustrated in Figure 15 shows three assemblies in a batch. Since lEOD cards are used as separators, 
BA must be specified on the IXSYMBOL card so that the assembler will reinitialize itself when it encounters the 
next source deck within the batch stream. Note that the parameters on IXSYMBOL could be in any order. 



/L 



!EOD (optional) 



z 



Source deck 



EOD (optional) 



Source deck 



IXSYMBOL LO,BO,BA 



iJOB 





_/ 



Figure 15. Assemble in Batch Mode 
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Figure 15. Assemble in Batch Mode (cont. ) 



ASSEMBLE AND EXECUTE IN FOREGROUND AREA 

An example of loading an assembly from the background |ob stream that is to be executed in the nonresident fore- 
ground area of memory is illustrated in Figure 16. The deck structure for such jobs is identical to batch Jobs 
except that the operator must key-in FG,S to access foreground memory and the foreground option (F) must be 
specified on the !OLOAD card (the default option is B for background). 



All access to protected memory from the background job stream must be preceded by an FG key-in. Failure 
to do so is a foreground write protection violation and aborts the job unless an lATTEND card is present. If 
an lATTEND card is present and the IPAUSE KEY-IN FG,S card Is accidently excluded, the Monitor will go 
into a wait state. The FG key-in must then be input and the command that caused the protection violation 
must be repeated. 



The first comma (preceding "F"), on the lOLGAD card informs the Loader by default that only a root segment is to 
be loaded; the "F" identifies the load module as a foreground task; and the triple comma specifies that the step 
mode and Debug options are not being used. The X parameter requests the Loader to abort the job If a sever- 
ity level greater than zero is encountered during the load process. 



The double comma on the !$RO0T card informs the Loader that the default temp stack size (80 cells) is to be 
used and that the default beginning execution location for the load module is to be K:NFFWA (nonresident 
foreground first word address) in the nonresident area of foreground memory. The GO option specifies that the 
Loader Is to read the single ROM (1) from the RBMGO file and write the load module Into the RBMOV file 
by default. 



The !$ML card causes the Loader to output a Long map when the load module Is written into RBMOV. 



The IPAUSE KEYIN FG,S card causes the system to go Into a wait state and outputs the message on the card to the 
operator's console so that the operator can perform the necessary FG,S combined key-In. This directs the Monitor to 
permit access to protected memory and continue processing. 



The IXEQ command causes the load module on OV to be loaded Into nonresident foreground memory for exe- 
cution, beginning at location KrNFFWA. 
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!FIN 



!XEQ 

! PAUSE KEYIN FG,S 



!EOD 



!$ML 



!$ROOT ,,GO,l 



lOLOAD ,F,,,X 



!EOD 



Source deck 



IXSYMBOL LO,GO 



lATTEND 



!JOB 




Figure 16. Load and Execute In Foreground Area 
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4. HOW TO CREATE AND MANIPULATE FILES 



Whenever you want to allocate space or create or maintain permanent files on a RAD or disk pack, you must first 
call in the RAD Editor. The RAD Editor interprets and executes Editor control commands that define the operation, 
area mnemonic, and file name to be used. 



Files to be saved achieve their permanent status by being created in the designated permanent area. Permanent 
areas are large blocks of RAD or disk pack space, each of which represents a grouping of files in terms of function. 
These permanent areas are initially set up at System Generation time and RBM will define the following areas by 
default if not defined by the user: 

System Processor area (SP) Contains language processors, nonresident portions of the Monitor, etc. 

System Library area (SL) Contains FORTRAN Library, etc. 

System Data area (SD) Generally contains the RBMGO and RBMOV files among other items. 

Checkpoint area (CP) Used for storing the background context when checkpointed by the 

foreground. 

Background Temp area (BT) Used as temporary scratch storage by background programs or processors. 

During SYSGEN, the default cases for any of these areas may be overridden. The following areas are of direct 
concern to the RAD Editor: 

System Processor area (SP) 

System Data area (SD) 

System Library area (SL) 

Background Processor area (BP) 

Foreground Processor area (FP) 

User Processor area (UP) 

User Data area (UD) 

User Library area (UL) 

Data area (Xn, where n is a hexadecimal digit) 

aa (where aa represents a two-character mnemonic on the Dictionary) 



You can put any type of file into any area desired. The area names are simply a convenience to expedite file 
housekeeping and management. The area names are formalized at SYSGEN and certain protection privileges 
are accorded to the areas, but what is put into these areas is up to you. Program files could be put into Data 
areas or vice versa. 

The very permanence of Editor-created files suggests that you exercise economy by not using up any more per- 
manent RAD or disk pack space than is strictly necessary, and instead, use temporary space in the BT area 
whenever possible. 
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The Background Temp area (BT) does not contain any permanent files and therefore is not the concern of the Editor 
since it cannot create files in this area. The Background Temp area contains the temporary scratch file (XI 
through Xn) that are used by processors and the users. 

• Management of permanent RAD areas and their files is handled by the RAD Editor via Editor control 
commands. 

• Management of the Background Temp area (BT) scratch files is controlled through ! DEFINE and ITEMP com- 
mands, or MrDEFINE Monitor service routine. 



Since the Editor is itself a background processor, use of RAD Editor services is performed through the background job 
stream. This means that a foreground program never calls the RAD Editor to perform services. The allocation and 
subsequent manipulation of both foreground and background files are performed as background job steps. 



Before discussing the use of the Editor and some of the control commands used to communicate with it, two terms must 
be clearly understood in the RBM context: 

• A record is the amount of information processed by a single Write or Read instruction, and contains a user- 
specified decimal number of bytes. This number of bytes constitutes the RECORD parameter (record size). 

• A file is an arbitrary, predetermined number of records that define the file's FILE parameter (file size). A 
file on the RADmust always have a name of three to eight EBCDIC characters by which it will be cataloged 
by the Editor in the proper permanent RAD area directory for all later calls to it. The file name is created 
by the user. Types of files include: program files that are interchangeably called executable programs or 
load modules; System and User Library files used by the Overlay Loader to satisfy external references in 
user's programs; and data files. Files are further categorized by FORMAT type: sequential, which may be 
U (unblocked), B (blocked), C (compressed); or random, which may be unblocked random (R) or (packed) 
random (P). 



HOW TO CREATE A FILE 

To create a file on the RAD for subsequent loading of either data or a background or foreground program, the Editor 
command 



/!#ADD 



areaname, filename 



is used. Since the Editor needs to know whether it has RAD space available whenever it encounters an !"^ADD 
command defining an area and a file name, it also expects you to specify 

file (file size) 

record (record size) 

format (blocked, unblocked, compressed, random, blocked random) 

on the same card, where as discussed previously, a file is a logically ordered group of records, and a record 
is the amount of information generally processed by one Read or Write request. FILE tells the Editor how many 
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records to allocate a file. RECORD tells the Editor the maximum number of bytes per record. FORMAT tells the 
Editor the structure of the file. However, RECORD and FORMAT do not necessarily have to be specified if you are 
willing to let the Editor give you default options. For descriptions on default options, see RAD Editor chapter in 
the RBM Reference Manual. To create a data file, the sample command 

!#ADD D1,SAMP,20,,U 



would define a file named SAMP to be allocated in the Dl area of the RAD. This file can contain up to 20 records. 
Since the "RECORD" was not specified, SAMP would have a default size of 360 bytes or 1024 bytes, depending on 
the RAD sector size where Dl is located. 



Assume the default size is 360 bytes; therefore, theabove PADDcommand would cause the Editor to reserve 7200 bytes 
of space in Dl under file name SAMP. So, the example has exactly the same effect as writing the command 

!#ADD D1,SAMP,20,360,U 



Using unblocked "FILE" format can sometimes waste space. For instance, if the purpose of the file SAMP is to hold 
the contents of 20 data cards (one EBCDIC card = 80 bytes of information), then 280 bytes in each one of the 
20 records is wasted RAD space, and better efficiency is needed. Change the format of the example to blocked 
and the record size to 80 bytes: 

!#ADD D1,SAMP,20,80,B 



For any blocked file, a 1 80- or 5 1 2-word blocking buffer is used to group as many records as will fit. If the blocking 
buffer is 180 words, in our new definition of SAMP above, four and one-half 80-byte records will fit in one block. 
Since it would take five blocks to contain 20 records, the amount of RAD space used would be five sectors. 

This is very efficient use of RAD space, so use this last version of !"^ADD to create a file as shown in Figure 17. 



I FIN 



!#END 



!#ADD D1,SAMP,20,80,B 



IRADEDIT 



! PAUSE INTERRUPT KEY-IN SY,S 



iJOB 



Note 1: Since the permanent file directories are software write-protected, an SY key-in must be initiated 
before updating or initializing a file directory if the area has an SY or FG protection code. 

Note 2: For RADEDIT, !#END is equivalent to lEOD. 



Figure 17. Create a RAD File 
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HOW TO DELETE A FILE 

A file is deleted by the Editor !* DELETE command. Any files may be deleted from the permanent file directory. To 
delete the SAMP file used previously, the deck structure shown in Figure 18 would be used. 



!FIN 



!#END 



l#DELETE D1,SAMP 



IRADEDIT 



! PAUSE KEY-IN SY,S 



UOB 



Dl is the area the file is located in and SAMP is file to be deleted. 



Figure 18. Deleting a File 



If the file deleted is the last file within the area, the space is automatically recovered without squeezing (see 
"How to Squeeze a RAD AREA" later in this chapter). 



HOW TO TRUNCATE A FILE 

The Editor I'^TRUNCATE command is used to delete unused but allotted space in a file by setting the EOT pointer 
equal to EOF. 



Let's examine a hypothetical cose. A blocked sequential file called BFILE of 100 records has been allotted. Thus, 
/l#ADD Dl, BFILE, 100,40 



Fifty records are copied into the file via the Utility COPY command (see Chapter 7 of this manual) and an EOF 
pointer is set at the end of the 50th record. Truncate the file as shown in Figure 19. 



The resulting file will only contain 50 records (even though 100 records were allotted on the I^ADD card) because 
the {^TRUNCATE card cut down the size of the file to the actual number of sectors required to contain the 50 rec- 
ords by moving the EOT pointer equal to the EOF pointer. 
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!FIN 



i^END 

!#TRUNCATE D1,BFILE 



IRADEDIT 



! PAUSE KEY-IN SY,$ 



UOB 



Figure 19. Truncating a File 

However, the space deleted via the !*TRUNCATE card is still trapped; that is, it cannot be accessed either by other 
files or file BFILE. Since file size reduction has already been performed, the RAD area must be "squeezed". 



HOW TO SQUEEZE A RAD AREA 



To release unused space in a truncated file and to recover space occupied by deleted files so that the system 

can use it, the RAD Editor {^SQUEEZE command is used. This moves all files forward and leaves empty space 

at the end of the area. It is inserted after the !*TRUNCATE card as shown in Figure 20, but note that it is 
not always necessary to truncate a file before squeezing an area. 



!FIN 



!#END 



!#SQUEEZE Dl 



!#TRUNCATE D1,BFILE 



IRADEDIT 



! PAUSE KEY-IN SY,S 



UOB 



Figure 20. Squeezing a RAD Area 
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After the processes illustrated in Figures 19 and 20 have taken place, you may wish to know how much space 
your file actually takes in the designated RAD area. To find out, the Editor !*MAP command is used as shown 
in Figure 21. 



!FIN 



!#END 



!#MAP Dl 



IRADEDIT 



!JOB 



Figure 21. Output a RAD Map 



This map provides a list of all the files in Dl area with their corresponding records and file sizes as shown in 
Figure 22. 
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Figure 22. RAD Area Map Example 

RAD area maps are a necessity, of course, when multiple users are creating files in a given area. Otherwise, the 
individual users would not know whether space is available in the area, whether a file with the same desired name 
already exists, etc. 

HOW TO ACCESS A FILE 

Now that we have created a file and initialized it with data, the problem of how to access the file remains. Files 
are read or written in background user programs in the same way that line printers, card readers, or other devices are 
accessed. The linkage between RAD files and your program is provided via [ASSIGN or commands inserted into your 
program deck. (See the [ASSIGN discussion in Chapter 2 of the RBM Reference Manual.) Foreground users access 
data files through Monitor service routines (Read/Write) coded into their programs. 



How to Access a File 
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HOW TO CREATE A PROGRAM FILE 

Before discussing th; technique for creating a program file that can be called into core for execution, a quick 
review of the two methods of accessing a file for either a Read or Write operation is necessary. 



SEQUENTIAL ACCESS 

When you use sequential access, you access a RAD file on a record-by-record basis (see definition of record given 
previously in this chapter) in exactly the same way that you access a data file on magnetic tape. This method can 
be used for blocked, unblocked, or compressed files. 



RANDOM ACCESS 

To perform random access you must supply the relative record number of the start of the Read/\Vrite request and the 
number of bytes to be transferred, where "relative record number" is the number of a granule relative to the start of 
the file for an unblocked file, or the relative logical record number relative to the start of the file for a blocked 
file. (A granule is defined by the user to be one or more sectors- ) The default (and typical) size is one sector for 
unblocked files. Addressing files by granules allows direct access to be independent of the RAD sector size. 



CREATION PROCEDURES 

All files are created in the same manner regardless of the functions for which they are to be used. This reduces gen- 
eral rules for program files to the following: 

• To save a load module (executable program) in a user-defined file, the file must be created with an Editor 
I* ADD command before a load module is stored into it. 

• The defined file must be a random access file. 



When you call in the Overlay Loader via the lOLOAD command to create a load module the Loader will print out 
the size of the load module on the load map, assuming you used one of the Loader map options. This size is given 
in sectors and since a load module is a random access file, this is the value to use as the FILE parameter entry on 
the Editor I^ADDcard. 



If you do not know the size of the load module until after it has been created, how do you know how to ["'ADD a 
file of precisely the right size? There are two solutions: 

1. Create the module on the OV file, which is the default output file for load modules. Look up the granule 
size on the resulting load map and use this number as the FILE parameter on an Editor !"^ADD card. Use on 
Editor !"^FCOPY card to copy the OV contents to the newly created file. 

Example: 



Assume the load module created with the Overlay Loader used 20 granules in the RBMOV file. Allot a file 
called FTEST of 20 granules in area Dl and copy OV out to the new file. The deck structure given in Fig- 
ure 23 would copy OV to the new file. 
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I lEOD 

— ^1 i^FCOPY OV,T1 

IRADEDIT 

"ASSIGN T1-FTEST,D1 



lASSIGN OV-RBMOV,SD 



!EOD 



!#ADD D1,FTEST,20,0,R 



IRADEDIT 



! PAUSE KEYIN SY,S 



UOB 



Figure 23. File Creation with Specific Granule Allotment 

2. Use an !"^ADD command to create a file that you know is sufficiently large for the load module. Put the load 
module into this file via an lASSIGN command prior to an lOLOAD command in the command stack, and then 
follow with Editor {"^TRUNCATE and !"^SQUEEZE commands that have a corresponding file specification. 

Example: 

Assume a new file called TESTl in area Dl is to contain a load module of unknown length. The deck struc- 
ture given in Figure 24 would allocate all available space to the file, load the module into the file, and 
then recover the unused space. 



U^ 



lEOD 



Source deck 




IXSYMBOL 



UOB 



!EOD 



1#ADD D 1, TESTl, ALL AR 



IRADEDIT 



! PAUSE KEYIN SY,S 



UOB 



\ 



y 



Figure 24. File Creation with Granule Over-Allotment 
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!FIN 



I lEOD 

Ji^SQUEEZE Dl 
!#TRUNCATE D1,TEST1 



IRADEDIT 



!EOD 



!$ROOT ,,GO,\ 



lOLOAD 



lASSIGN 0V = TEST1,D1 



Figure 24. File Creation with Granule Over-Allotment (cont. 



HOW TO CREATE A NEW LIBRARY 

A library consists of six files: MODIR, EBCDIC, EDFRF, BDFRF, MDFRF, MODULE. These files are allocated in 
either the System Library (SL) or User Library (UL) areas, as appropriate (these are the only two areas that can have 
libraries), and the files must have the exact names given above and be in random format. 



For instructions on how to compute the sizes of each file for a particular library, see the RAD Editor chapter in the 
RBM Reference Manual. 



All library files are random files. In the !*^ADD command example 
/!#ADD SL,MODIR,6,S,R,SY 



the "6" parameter following the file name MODIR means a size of six records in the SL area. Since"RECORD" is S, 
you have specified that you wanted RECORD = SECTOR size. The FORMAT "R" specifies an unblocked random access 
file. The Write parameter "SY" means write permitted when the SY key-in is in effect. When computing the sizes 
of the files from the formulas in the RAD Editor chapter in the RBM Reference Manual, remember that the results will 
be in granules or the number of records needed. If you do not have enough information to compute the size of each 
file, allocate them a greater number of sectors than are required. 



After all six files have been created with "^ADD commands, the "^LADD command enters the library routines into 
the defined four files, depending on the library code parameter on the !"^LADD command: Basic (B), Main (M), or 
Extended (E) as defined in Figure 25. The same basic method is used to set up the User Library. 



Note; If you ever plan to add new programs to a library or replace existing library routines with larger rou- 
tines, omit the {'^TRUNCATE command. 
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___!#END__ 
!#SQUEEZE SL 
!#TRUNCATE SL 



zr 



z 



Object module 



!#LADD SL,,M 




Object module 




!#LADD SL,,E 






J/ 



Object Module 




!^LADDSL,,B 



!#ADD SUMODULE,ALL,S,R,SY 



!#ADD SL,MOFRF,2,S,R,SY 



!#ADD SUBDFRF,2,S,R,SY 



!#ADDSUEDFRF,2,S,R,SY 



!#ADD SUEBCDIC,6,S,R,SY 



1#ADD SL,MODIR,3,S,R,SY 



IRADEDIT 



! PAUSE KEYIN SY,S 



!JOB 



y 



Note that SY,S Key-in is required to write into the SL area. This would also be required 
for creating a library in the UL area. 



Figure 25. Input Library Files 



HOW TO ADD A LIBRARY ROUTINE 



Since the library already exists, the method for adding a new routine is quite simple, as illustrated In Figure 26. 
This example Is essentially the same deck structure used to create the library, except that you ADD onto the end of 
the existing library files. The example assumes that BI has been assigned to the card reader. 
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JFIN 
!#END 



/ 



Object Module (RDATA IDENT) 



!#LADDSURDATA,M 




IRADEDIT 



! PAUSE KEY-IN SY,S 



!JOB 



Note; The *LADD command adds an object module to the designated library. 

The "identification" parameter identifies the object module being loaded. 



Figure 26. Add a Library Routine 



HOW TO DELETE A LIBRARY ROUTINE 

To delete a routine from a library it is first necessary to determine the name associated with each routine in that li- 
brary via a RAD Editor !"^LMAP command. Besides listing a name for each routine on the RAD map, it also lists all 
other entry points or data words in each routine. 

The !*LDELETE command deletes an object module specified in the identification parameter from the designated li- 
brary as shown in Figure 27. 



!EOD 



!#END 



!#LDELETESULABS 



IRADEDIT 



I PAUSE KEY-IN SY,S 



IJOB 



Figure 27. Delete a Library Routine 
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HOW TO RECOVER UNUSED LIBRARY SPACE 



If- is someHmes desirable fo recover previously used file space and to make it available for storing other library 
routines after a routine has been deleted. The PLSQUEEZE command is used to release the space. The 
!*LSQUEEZE command shown in Figure 28 would restore the space formerly occupied by the LABS routine in 
the System Library files. This command does not change the file sizes allocated but compacts the data in the 
files. 



!FIN 



!#END 



!#LSQUEEZE SL 



!#LDELETE SL,LABS 



IRADEDIT 



[PAUSE KEY-IN SY,S 



!JOB 



Figure 28. Library Space Recovery 



HOW TO REPUCE A LIBRARY MODULE 



During the evolution of a routine in a User Library, updates are very common in the development of the final oper- 
ational version. The !*LREPLACE command is used to replace an existing intermediate object module with a newer 
object module bearing the same identification. This command will not recover the space occupied by the replaced 
routine. 



Examph 



Assume a BASIC library routine called "BLIB" that is located in the User Library. To replace this routine with an 
updated version, the deck structure shown in Figure 29 would be used. (The example assumes that BI has been 
assigned to the card reader. ) 
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!FIN 
!#END 



Object module 



!#LREPLACE UUBLIB,B 



IRADEDIT 



! PAUSE KEY-IN SY,S 



!JOB 




Figure 29. Replace Library Object Module 

Note that the space used by the original BLIB would not be recovered, and that the new BLIB would reside at the 
end of the current library. 
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5. HOW TO BUILD AN OVERLAY PROGRAM 



Use of the Overlay Loader with nonoverlay programs has been covered in the examples given in the FORTRAN and 
Extended Symbol chapters, and it is now necessary to discuss some of the ways the Loader can be used to create seg- 
mented (overlay) programs. 

The only purpose in overlaying a program is to minimize core size requirements. Since there is a slight degradation 
in response time for each level of overlay within a foreground program, it is obvious that such programs should not 
have any more overlay levels than are absolutely necessary. 

Before discussing overlay techniques, the term ROM must be fully defined: 

• A ROM is a Relocatable Object Module, and is the only type of object module the Overlay Loader will 
accept to form the load module. "Relocatable" means that the execution location in core for the module 
is determined by the Overlay Loader at load time. 

The other type of object module is absolute; that is, a fixed execution location is determined by the user at assembly 
time through use of the Extended Symbol (or SYMBOL) ASECT and ORG directives. Absolute object modules are 
loaded by another processor called the Absolute Loader, and are always executed in the same predetermined loca- 
tion unless reassembled. 

Every reference to "object module" in this manual always means ROM, and this term is used by the Overlay Loader 
when it outputs a load map or diagnostic message. 

The material and examples in this chapter do not encompass every option available to the Loader user; rather, the 
chapter presents what constitutes an overlay'job and the interface between basic structures and several Loader con- 
trol commands. A study of the examples will make the significance of other Loader commands and options (i.e., the 
!$TCB command described in later chapters) more apparent. 

The presence or absence of a single option on the iOLOAD command (F), causes the Loader to define the resulting 
program as either background or foreground (B is the default case). All of the examples below are relevant to both 
foreground and background programs. 

Assume the following program: 

1. A Main program that calls in subroutines A, B, and C. 

2. Subroutine A does not reference subroutines B or C. 

3. Subroutine B does not reference subroutines A or C. 
3. Subroutine C does not reference subroutines A or B. 

This program could be loaded into memory in nonoverlay form to appear as 

I Main I A i B i C i 



low memory j 1 high memory 
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However, If the program was segmented, it would take up less memory and would appear as 

A 



Main 



(root segment 0) 



(segment 1) 



B 



(segment 2) 



(segment 3) 



low memory L 



high memory 



where subroutine A is not residing in memory (saved on the RAD) when subroutine B is in memory, and vice versa. 
Note that the root segment is always resident and is designated as segment 0. The Main program (root segment) has 
the responsibility of calling the appropriate segment into memory (see "Communication Between Segments" later in 
this chapter). 

Assuming the ob|ect modules are residing on the GO file in the order Main, A, B, and C, the structure could be 
created by the following set of commands which would create the overlay structure pictured above: 



IXEQ 



!EOD 



1$MP 



l$SEG 3,0,GO,1 



!$EG 2,0,GO,1 



1$SEG 1,0,GO,1 



!$ROOT ,,GO,l 



!OLOAD3,B 



The structure is defined by the !$ROOT and !$SEG cards. The first l$SEG card defines segment number 1 to be 
connected to segment number (root). The second and third !$SEG cards correspondingly define segments number 2 
and 3, also connected to the root. 



For another example, assume the following program: 

1. A Main program that calls subroutines A and B. 

2. Subroutine A calls subroutine C. 

3. Subroutine B calls subroutine C. 

4. Subroutine A does not reference subroutine B. 
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This program could be segmenl-ed in the following manner: 



Main 



(roof)- 



(segmenf 1) 



B 



(segment 2) 



low 



high 



allowing C to be available to both subroutines A and B without an extra copy of C being necessary- However, as- 
suming the order on the GO file is Main, C, A, and B, then using the previous control command string would give 
you the unworkable structure 

-I 



Main 



(root) 



(segment 1) 



(segment 2) 



B 



(segment 3) 



which does not allow the required calls. Since this structure does not allow A or B to call C and then to continue 
upon C's return (C will wipe out A or B in memory), it is obvious that the simple structure we used above cannot be 
used to solve this problem. 

The following control cards could be used instead: 



!$SEG 2,0,00,1 



!$SEG 1,0,00,1 



!$ROOT ,,GO,2 



lOLOAD 2 



These commands put the first two routines on the OV file in the root, and one routine each in segments 1 and 2. 

Full understanding of the use of the l$ROOT and !$SEG commands is imperative for segmenting programs. Assume 
the following program: 

1. The Main program calls in subroutines A and B. 

2. Subroutine A does not reference routine B. 

3. Subroutine B does not reference routine A. 

4. Main, A, and B are to be input via the card reader (the binary input (BI) device). 
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The following command structure is needed (assuming the commands are also read in from the card reader): 



Object module B 



z 



!$SEG 2,0,BIJ 



Object module A 



!$SEG 1ABI,1 



Object module Main 



!$ROOT ,,BI,1 



lOLOAD 2 






/ 



_/ 



y 



whenever more than one module is needed, the number is required, or a blank may be used. If no number is speci- 
fied the Loader expects to encounter an !EOD command following the object modules before any other Loader sub- 
command is encountered. Let's consider a slightly more complex example. 



Assume the following program: 

1. A Main program that calls subroutines A and B. 

2. Subroutine A calls subroutine C, D, and E. 

3. Subroutine B calls subroutine C. 

4. Subroutine D calls subroutine C. 

5. Subroutine E does not reference any routine. 

6. Main, A, and E are on magnetic tape; opiabel MO. 

7. C and D are on magnetic tape; opiabel Ml. 

8. B is on the GO file. 
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Thus, the overlay structure Is 



Main 



(segment 1] 



(segment 4) 



D 



(segment 2) 



(segment 3) 



low 



high 



and the control command sequence could be 



!$END 



!$SEG 4,0,GO,1 



l$SEG 3,1,M0,1 



!$SEG 2,1,M1,1 



!$SEG lAMOJ 



!$LDM1,1 



!$ROOT ,,MOJ 



!$MP 



10L0AD4 



Whenever the overlay structure is such that some segments link to segments other than the root, there is an order to 
the !$SEG commands that must be followed. This can be Illustrated by the following example: 



(root) 



(segment 1) 



(segment 4) 



(segment 2) 



(segment 3) 
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As soon as segment 1 is defined, all segments linking to it (segments 2 and 3) must be defined via !$SEG commands 
before !$SEG 4,0, can be encountered. 



Let's take a look at another example: 









(segment 3) 




(segment 2) 


1 




(segment 1) 


(segment 4) 


1 


(segment 5) 




' (root) 






(segment 7) 






(segment 8) ' 






(segment 6) 






(segment 9) 





In this case, after a l$SEG 1 command is input, either segment 2 or 5 may be defined. However, whenever seg- 
ment 2 is defined, then all segments linked to it must be listed next (i.e., segments 3 and 4). There are several 
deck structures that could be used to construct the overlay above. One of these deck structures is shown below: 



These two segment defini- 
tions could be interchanged 
since no other segment links 
to them. 




!$SEG 4,2,xx,l 



!$SEG 3,2,xx,l 



!$SEG 2,1,xx,1 



!$SEG 5,l,xx,l 



l$SEG l,0,xx,l 



!$ROOT ,,xx,l 



lOLOAD 10 



^here xx denotes the opiabel where the module resides 
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Another deck structure Is as follows: 



l$SEG5,l,xx,l 



!$SEG 4,2,xx,l 



l$SEG 3,2,xx,l 



!$SEG 2J,xx,1 



!$SEG l,0,xx,1 



!$ROOT ,,xx,l 



IGLGAD 10 



However, the following deck structure cannot be used since all segments linked to 2 must follow the !$SEG 2,l,xx,l 
command: 



!$SEG3,2,xxJ 



l$SEG 4,2,xx,l 



l$SEG 5,1,xx,l 



!$SEG 2,l,xx,l 



!$SEG lAxxJ 



!$ROOT ,,xx,l 



lOLOAD 10 



There is no general rule regarding the actual numbers selected to designate segments. Segment numbers may range 
from 1 to 255 and may appear in any order. The segment numbers are needed for communication between the user 
program and the Segment Loader during execution. 
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COMMUNICATION BETWEEN SEGMENTS 

since the primary objective of the RBM operating system is to provide fast response and processing for real-time 
users, there is no automatic loading of overlay segments as the result of a reference to a routine within the segment. 
If the root only occasionally uses segment 2 in the following structure, then it can call it in, use it, and continue 
on without having waited for segments 1 and 20 to be brought in. 



(root) 



(segment 1) 



(segment 20) 



(segment 2) 



(segment 87) 



(segment 14) 



(segment 17) 
This permits the real-time user to manage the overlay process in the most efficient manner for a given program. 
The exact procedure for calling in segments is different for the FORTRAN user and the assembly language user. 

FORTRAN SEGMENT CALLS 

A FORTRAN user calls in a segment with the statement 

CALL SEGLD (I) 
or 

CALL SEGLD (I, J) 

where 

I is the segment number. 

J is the file from which the segment is to be loaded. 

In the case where J is not designated, the PI (processor input) file is assumed. 



However, a call to SEGLDX causes an overlay segment to be loaded and control transferred to the transfer address 
of the segment. A call to SEGLDX has the form 

CALL SEGLDX (I) 



CALL SEGLDX (I, J) 

where 

I is the segment number. 

J is the file from which the segment is to be loaded- 

In the case where J is not designated, the PI (processor input) file is assumed. 
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ASSEMBLY SEGMENT CALLS 

Assembly language users are provided with system calls for segment loading and hove a choice as to how to load 
segments. They may 

1. Load the segment and return. 

2. Load the segment and transfer to the "starting address" of the segment upon completion of the load. The 
"starting address" is defined by a label on the END card of the assembly, or the FWA (first word address) 
of the segment by default. 

3. In foreground, request the segment to be loaded and do not wait for the load to take place. Instead, spe- 
cify a "loading-complete" receiver, which would transfer to a specified address when the I/O interrupt be- 
comes active (any processing performed by the "end-action" routine should be kept as short as possible to 
prevent degradation of response time for lower-priority interrupts). 

SEGMENT COMMUNICATION USING COMMON AREAS 

Blank COMMON 

Both FORTRAN and Extended Symbol users can define blank COMMON either in their source code or through the 
cmn parameter on the I O LOAD card. 

In allocating COMMON for background programs, the Loader compares the cmn parameter with the first nonzero 
COMMON size allocation value encountered in loading and employs the larger of these two values. The COM- 
MON base is set by subtracting the COMMON size from the upper limit of core memory. 

For foreground programs having blank COMMON, cmn denotes the base (i.e., first word address) of COMMON. 
In this case, the effective upper limit of the program is cmn plus the largest COMMON size allocation value en- 
countered in loading. For foreground programs in which COMMON is allocated but in which cmn has not been spe- 
cified, the COMMON base is set by subtracting t he first nonzero COMMON size allocation value encountered from 
the upper limit of nonresident foreground memory. Foreground programs that have no COMMON may use the cmn 
parameter to specify an upper limit for the program, if the address specified by cmn is higher than the root FWA. If 
the program exceeds the limit, the Loader aborts. The default value of the upper limit for foreground programs with- 
out COMMON is the upper limit of the nonresident foreground area. 

Foreground loads may specify the cmn parameter at a lower address than the root FWA; in which case, the end of 
nonresident foreground is the program upper limit. A check is made at the end of the load to determine whether the 
COMMON allotment overlaps the root. If it does, the warning message "OLERR CO" is printed out but no error 
severity level is set. 

See also the subsection "Blank COMMON Storage" in Chapter 8 of this manual. 



Labeled COMMON 

Labeled COMMON is defined in the source code and labeled COMMON areas precede the module in which they 
are first defined. 

• A fresh copy of the labeled COMMON is brought into memory as each segment with a labeled COMMON 
is loaded. This means that any data the programmer wishes to save between segments that occupy the same 
memory area should be either in blank COMMON, or in labeled COMMON in a segment that does not get 
overlaid while the data is still pertinent. 

• The FORTRAN IV compiler is capable of using labeled COMMON directly, but Extended Symbol must first 
REF the labeled COMMON block, which will give the start address of the block; access is achieved through 
the source code. 
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HOW TO READ A LOAD MAP 

The primary Intenf-lon in outputting a load map is to simplify the programmer's job when a set of programs fails to 
satisfy all external references. Additionally, various size and location information is output to simplify the task of 
file and core allocation. The Load Map shown in Figure 30 is the most extensive of the map options and is produced 
by the control command l$ML. 

For the !$MP command, the same information is output except for the Public Library and Monitor service DEFs (the 
list of names between the lines marked OVERLAY TASK and ROOT), and Library symbols (those denoted by an L 
immediately to the right of the symbol name; XrERROR, for instance). 

The !$MS command outputs only the header lines; that is, the lines marked OVERLAY TASK, ROOT, SEGMENT, 
ERRSEV, and END AAAR. 

All size and location data is in hexadecimal. The terms "core location" and "address" in this discussion refer to 
core locations at execution time. 

The OVERLAY TASK line gives information about the entire overlay cluster. From left to right, the various items 
have the following meaning: 

BA: means a background program; foreground programs cause "FO" to be printed. A map will show 

either BA or FO. 

ORG: means first (lowest) core location of the program's temporary stack (see RBM Reference A/\anual). 

HLOC: means highest core location of the overlay cluster. 

CBAS: means first core location of the blank COMMON area. 

CSIZ: means size of the blank COMMON area in words. 

UMEM: means unused memory, the difference between HLOC and CBAS (the amount of memory available 

to the Monitor for blocking buffers). 

SECT: means the number of sectors required by the overlay cluster in a processor file. 

Following the first line is a list of all the DEFs in the Public Library. These are flagged by the P to the right of the 
name; the M indicates that this routine was placed in the Public Library in the Main mode. The other possible modes 
are Extended and Basic and are flagged by an E and a B, respectively. 

The remainder of the DEFs in this list are the various Monitor service routines. The numbers to the right of the Pub- 
lic Library DEFs and the Monitor service DEFs are their respective core locations in the Monitor's "Transfer Vector 
Table" (see Chapter 4 of the RBM Reference Manual), which is a table maintained by the Monitor for its own use in 
locating these routines. 

This list will not change (for any load with an !SML command) unless a user changes the Public Library, in 
which case only the Public Library DEFs will change. 



The ROOT line contains the following information: 

ORG: means the first core location of the root's program section for a background program, or the loca- 

tion of the TCB for a foreground program. 

LWA: means the last core location of the root (Including whatever library routines are in the root). 
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MAP 














SV£RLAY TASK 


8A 9RGp6000 HU8C- 


61F3 CBASaFoOO CslZsQOOO UMEMeSEoC SECT. 0006 


DEF 


PLJSECT 




P 


M 




1FB4 


DEF 


PL5RDCHK 




P 


M 




1FB5 


DEF 


PL.'WTCHK 




P 


M 




1FB6 


DEF 


pljread 




P 


M 




1FB7 


DEF 


PL; WRITE 




P 


M 




1FB8 


DEF 


M, 


fsave 










C47C 


DEF 


D! 


<EY 










1F9B 


DEF 


Dl 


CARD 










1F9C 


DEF 


D! 


SNAP 










1F90 


DEF 


Ml 


SAVE 










1F96 


DEF 


M! 


EXIT 










lF97 


DEF 


M 


leEX 










1F9E 


DEF 


Ml 


READ 










IFAC 


DEF 


M 


WRITE 










iFAl 


DEF 


y 


.CTRL 










1FA2 


DEF 


M 


TERM 










1FA4 


DEF 


M 


DATIVE 










1FA3 


DEF 


y 


lABeRT 










lFA5 


DEF 


M 


'HEXIN 










1FA6 


DEF 


M 


inheX 










1FA7 


DEF 


M 


ckrfst 










1FA8 


DEF 


M 


LeAD 










lF98 


DEF 


M 


:t}PEN 










1FA9 


DEF 


M 


;CL9sE 










IFAA 


DEF 


M 


;0<EVS 










If-'AB 


DEF 


M 


iWAlT 










IFAC 


DEF 


M 


!Se3LD 










IFaD 


DEF 


M 


IDEFINE 










IFAE 


DEF 


M 


[ASSIGN 










IFAF 


DEF 


M 


SQPFlLE 










IFBC 


DEF 


M 


{PpP 










IFBl 


DEF 


V! 


!RES 










1FB2 


DEF 


y 


:dym 










1FB3 


DEF 


V, 


IRSVP 










IF99 


DEF 


M 1 


■Dew 










1F9A 


DEF 


M 


cec 










IF9F 


RSBt 8RGs6050 


Li^A«6lB7 


L£^, 


.0168 


TRAa6c50 SEv«0000 '^V : !-eiADs6052 


DEF 


XiERReR 


L 


S 


M 




61U 


DEF 


xidir 


L 


S 


M 




60ED 


oe^ 


L:dir 


L 


s 


M 




6GeD 


DEF 


USER^SR 


L 


s 


M 




611^ 


DEF 


m:push 


L 


s 


M 




6I7F 


DEF 


XjCK 


L 


s 


M 




607A 


DEF 


LJCK 


L 


s 


M 




607A 


DEF 


L:33R3 


L 


s 


6 




6061 


DEF 


LI33R? 


L 


s 


B 




6065 


DEF 


L:33Rl 


L 


s 


B 




6069 


DEF 


9V;L8aD 


I 








6052 


P REF 


SEG2 


I 








0002 


P REF 


SEQl 


I 








0001 


DEF 


SUBi 


I 








6051 


SEGMENT IDE^T 


N80E 9RG 


UWA 




len 


TRA SEV 


0001 


0000 fclBS 


6 


LI-: 


3 


C03C 61BR 0000 


DEF 


M:3R 


L 


s 


M 




61E3 


DEF 


AINT 


L 


s 


B 




61BR 


DEF 


LSAIMT 


L 


s 


B 




6IBB 


DEF 


segi 


I 








61B8 



Figure 30. Loop Map Example 
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SEGMENT IDEMT W9DE BRG LWA LEM TRA sEV 
0002 0000 61B8 610B OOS** 61B§ QOOO 



DEF 


X;3N 


L S M 


6IC3 


DEF 


l:3N 


L S M 


61C3 


DeF 


m:sR 


L S M 


61C8 


DEF 


ABS 


USB 


61B9 


DEF 


SEG2 


I 


6IB8 



FRRSEV. 0000 



FND MAP 



ET.C00«3-'? 

10/20/71 1555 rK»000t35*F38000'02i ID=00C«0C 

Fin 



Figure 30. Load Map Example (cont. ) 

LEN: means the overall root size in words. 

TRA: means the root's entry point, which is determined by the argument of the END statement in a 

program written in assembly language. 

SEV: means the error severity level; the highest error severity encountered in loading the root (either 

assembled or Loader -generated) - 

OV:LOAD: means the OV Load Table location, which is a 5-word-per-entry table generated by the Loader 
at the end of the root's program section. It contains information to allow the Monitor to locate 
and load into core the segments of the program at run -time. If there is only a root, no OV Load 
Table is generated, and instead of a core location, the word NONE is printed. 

Following the ROOT line is a list of DEFs and REFs encountered while loading the root (including library routines). 
Each symbol (name) is error-flagged or identified by one or two characters as follows: 

For DEFs: D means duplicate. 

U means a DEF statement was declared (in the code) but no value was given (there was no label 
in the routine matching the argument of the DEF statement). 

LC means a Labeled COMMON block was defined. 

For REFs: U means unsatisfied; the Loader could find no matching DEF while loading this path. 

P means a primary Reference (REF). 
S means a secondary Reference (SREF). 



To the right or each name are from one to three characters denoting the input source for that name. An "L" signifies 
a library file, "S" signifies the System Library (a "U" would signify the Users Library and a "P" would signify Public 
Library), and a "B", "E", or "M " signifies Basic, Extended, or Main mode respectively. An "I" to the right of a 
DEF means that it was encountered during the program load of this segment; for a REF, the "I" means that a match- 
ing DEF was found in a higher level segment. 
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The numbers in fhe rightmost column denote the first core location of the routine containing that DEF or the segment 
number containing a DEF which matches that REF; i.e., primary REF SEGl is "satisfied" in segment number one. 

Note that there are several pairs of Library routines whose core addresses are the same, e.g., X:DIR and L:DIR. 
This signifies that these are different DEFs (entry points) in a single module. 

When the Loader satisfies an external REF in the same segment, the symbol table entry for that REF is changed to a 
DEF. Thus, although the program whose map is illustrated contained a REF SUB! in the root, it is not printed since 
a DEF SUBl was encountered during root loading. 

The information in a SEGMENT line differs from that in a ROOT line in three items, as follows: 

1. There is no OVrLOAD entry since only the root has an OV:LOAD table. 

2. The number under the IDENT is the first parameter on the ISSEG card for that segment. It is the Seg- 
ment Identifier. 

3. The number under the "NODE" is the second parameter on the !$SEG card. It is the segment identifier of 
that segment to which this segment is connected. 

The listed information following the SEGMENT line is exactly similar to that following a ROOT line. 

The ERRSEV line shows the highest error severity level encountered during the entire program load and the END 
MAP line is self-explanatory. 



LOADER PROCESS SUMMARY 

During the loading process, the Loader must exist in background core together with the absolute load module version 
of the segment being loaded, plus various tables that are required for linkage. One such table is the Segment Table, 
which requires 10 (N+2) cells, where N is the number of segments specified on the lOLOAD card. The Segment 
Table is located at the highest available core locations. 

Below the Segment Table are the various Symbol Tables, all of which have the same entry format. Each entryrefers 
to a specific definition or reference. The entries are of variable length, from five to eight words, depending on the 
number of characters in the DEF or REF symbol. 

The Permanent Symbol Table is a set of DEFs of the Monitor service routines; typically 230 words in length where 
there is no Public Library. If a Public Library exists, a Permanent Symbol Table entry is generated for each DEF in 
the library, again from five to eight words in length. 

Below the Permanent Symbol Table, the Loader builds the Root Symbol Table, working from high core toward low 
core. The Loader is also building the absolute core image of the program, working from low core toward high core. 
(If the program should meet the Symbol Table, table overflow occurs and the load is aborted. ) Whenever a REF is 
seen in the root, the currently existing Symbol Tables are searched for a satisfying DEF. If none is found, the REF 
is added to the root symbol table. 

When the program portion of the root is completely loaded, it is written to the OV file, and the specified or default 
libraries are searched for any unsatisfied REFs in the Symbol Table. When all the library DEFs that match any un- 
satisfied REFs have been loaded, the library portion of the root is written to the OV file. Segment loading then 
proceeds similarly to the root loading, except that the program and library portions of each segment are loaded to- 
gether, and then written to the OV file. The Segment Symbol Tables are built below the Root Symbol Table (again 
working from high toward low core) until a new path (or portion of a path) is begun, at which time that part of the 
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Segmenf- Symbol Table that refers to the just-completed path is written to a temporary file (opiabel XI). Assuming 
no overflow or other problems are encountered, this process continues until the program is completely loaded. Then 
PASS2 of the load process commences, where all forward REFs are linked and any requested maps are output. 



The important factors in segmenting a program are these: 

• Program segment sizes (including library code) 

• Number of segments 

• Number of DEFs and REFs in each ROM 

• Response time requirements 

The diagram in Figure 31 illustrates the layout of core during the load process. 
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Figure 31. Core Layout During Loading 
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6. HOW TO USE MONITOR SERVICE ROUTINES 



Most previous discussions and examples in this manual concerning communication with the Monitor have dealt with 
control commands and key-ins used in the background job stream prior to execution of an operational program. 
Monitor service routines are the means used by an executing program or task to request I/O, privileged operations, 
or other services from the Monitor. Service routines are the only means by which the background can perform I/O 
or privileged instructions. 

You request a Monitor service routine by establishing a pointer to an argument list, a return link such as a register 
copy and increment (RCPYI), and a branch instruction coded into your source program prior to assembly, or com- 
pilation. The techniques for branching to the service routines are primarily the concern of assembly language users, 
since FORTRAN users normally call these services indirectly through FORTRAN Library routines. Note however, 
that Xerox ANS FORTRAN has an in-line assembly language capability via an "S" in column 1, and this capability 
permits branches to Monitor service routines without going through the FORTRAN Library. 

There are three easy ways to access the various Monitor service routines. The first two are basically the same; that 
is, by branching indirectly through a fixed RBM Zero Table location. These locations are obtained by referencing 
the Transfer Vector Table for Monitor Services in Chapter 4 of the RBM Reference Manual. This table will supply 
the address associated with the desired routine, and Note 1 in the same table gives the steps tofollow when coding. 

In small developmental routines, it is often convenient to use the actual Zero Table location, as in this call to 
MrWRITE: 



LDX 
RCPYI 



=ARGLIST (pointer to argument list) 

P,L (return link) 

*X'CA' (indirect branch through vector location) 



ARC LIST DATA 

BUFF TEXT 



X'30O5', 'LO', BUFF, 18 (parameter list) 
'bWRITE TO PRINTER' 



However, in larger and more complex programs, it is often convenient to create a set of EQU directives that equate 
mnemonically satisfying labels to the appropriate core locations, as follows: 



VrREAD 
VrWRITE 



EQU 
EQU 



X'C9' 
X'CA' 



Definition of Zero Table locations 



LDX =ARGLIST 

RCPYI P,L 

B *V:READ 



Program section: call to M:READ 



As shown above, the branch indirect is accomplished exactly as in the first example; the difference being only 
one of convenience. 
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The third method is to reference the appropriate service routine at the beginning of each program element. This is 
easier from a programming standpoint, since you need not know the fixed core locations. The Loader will create 
the required linkage at load time. However, the cost of such simplicity is increased core requirements. During 
loading, each REF creates an additional Symbol Table entry. (See the Overlay Loader, Chapter 7 in the RBM 
Reference Manual and Chapter 5 in this manual.) Programs using this technique may require reloading when a new 
version of the Monitor is installed. An example of this type of access would be 

(Routine start) 



REF 



MrREAD, MrWRITE, MrLOAD, , 



LABEL 



RCPYI 


P,X 


B 


LABEL 


DATA 


X'380T, "XT, BUFF, 360, 2 


RCPYI 


PA 


B 


MrWRITE 



The above example also illustrates a slightly different method of entering the address of the MrWRITE argument list 
into the index (X) register. 

All of the examples described assume the existance of a set of register equates in the program of the formr 



EQU 
EQU 
etc. 



See Chapter 4 of the RBM Reference Manual for detailed descriptions and argument list requirements for each Moni- 
tor service routine. 

Figure 32 shows assembled examples of some of the most frequently used service routines (see also Chapter 9 in this 
manual, "How To Use Standard Procedure Files"). Note that none of the examples are set up to be executed, but 
only illustrate how Monitor service routines are coded within a program. 



1 










REF 


MlWRlTEiMJREAD^MJCTRLiMlDATlMEjMIABP'^T^M.'HEXlN 


2 










REF 


""lllBAD^MjePEM/MjASSTGM.M'.SEGLD^MSOFFlNE^M'.RES 


3 










REF 


evjLOAD 


4 




0001 


A 


P 


EQU 


1 


5 




0002 


A 


U 


EQU 


2 


6 

7 
8 
9 

10 




0003 


A 


T 


EQU 


3 








# 


THIS 


ROUTINE WILL WRITE TO TTY 


0000 


C85E 


A 




LDX 


"LISTl 


11 


0001 


75A1 


A 




RCPYI 


ftl 


IS 


0002 


4C5D 


A 




B 


h:write 


13 


0003 
0004 
0005 
0006 


3005 
D6C3 
0007 
OOOA 


A 
A 
R 
A 


LISTl 


DATA 


X'3005'*'BC'*MESS*10 


U 


0007 
0008 
0009 
OOOA 
OOOB 


40C8 
C9f0 
E3C8 
C509 
C540 


A 
A 
A 

A 

A 


MESS 


TEXT 


' HT TMERE» 



Figure 32. Monitor Service Routine Examples 
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15 








• 






16 








» 


THIS RSUTINE WILL READ AN EBCDir CARD | 


17 








# 






18 


oooc 


C854 






LDX 


''LIST2 


19 


OOOD 


75A1 






RCPYI 


P*L 


20 


OOOE 


4C53 






B 


MtREAD 


21 


OOOF 
0010 
0011 
0012 


3006 
E2C9 
0013 
0050 


R 
A 


LIST2 


DATA 


X'3o06ti'Sl'iBUFFj8o 


22 


0013 






BUFF 


RES 


40 


23 








• 






2* 








• 


THIS WILL REWIND THE MT eNLlNE 1 


25 








« 






26 


003B 


C827 


A 




UDX 


•LIST3 


27 


003C 


75A1 


A 




RCPYI 


P#L 


28 


003D 


4C26 


A 




B 


M;CTRL 


29 


003E 
003F 


003B 
C1C9 


A 
A 


LIST3 


DATA 


X»3B'*'AI» 


30 








* 






31 








* 


THIS RBUTINE WILU FIND THE TIME | 


32 








* 






33 


0040 


C824 


A 




LDX 


•LIST4 


34 


0041 


75AI 


A 




RCPYI 


P*L 


35 


0042 


4C23 


A 




B 


MJDATIME 


36 


0043 


cooo 


A 


LIST4 


DATA 


X'COOO' 


37 


0044 


0045 


R 




ADRl 


TIME 


38 


0045 






TIME 


RES 


7 


39 








* 






*0 








• 


THIS PRINTS ABeRT C9DE AB AT LftC 1?34 | 


'^l 








« 






42 


004C 


881A 


A 




LDA 


•1234 


43 


004D 


C81A 


A 




LDX 


•'AB' 


44 


004E 


75A1 


A 




RCPYI 


P,L 


45 


004F 


4C19 


A 




B 


Ml ABORT 


46 








• 






47 








« 


CONVERT 


ROUTINE 


48 








« 






49 


0050 
0051 


ClC2 
C3C4 


A 
A 


INPUT 


DATA 


'AB«*»CDI TB BF CONVERTED 


50 


0052 
0053 


1096 
89FD 


A 
A 




LDD 


INPUT 


51 


0054 


75A1 


A 




RCPYI 


P#L 


52 


0055 


4C14 


A 




B 


MJHEXIN ACC RETURNED WITM X«A8CD» 


53 








* 






54 








« 


TB L8AD 


PROGRAM FILE 


65 








« 






56 


0056 


C814 


A 




LDX 


•LIST5 


57 


0057 


75AI 


A 




RCPYI 


P/L 


58 


0058 


4C13 


A 




B 


MSLOAD WTLL CAUSE THE LOADIMG OF THE RO^T 


59 


0059 


4000 


A 


LIST5 


DATA 


Xt4000' OF TME LOAD MODULE 'FILE' AT THE 


60 


005A 
005B 
005C 

005D 


C6C9 
D3C5 
4040 

4040 


A 
A 
A 

A 




DATA, 4 


'FILE » CRNTRBL TAS< LEVEL 


61 


005E 
005F 
0060 
0061 
0062 
0063 
0064 
0065 
0066 
0067 
0068 
0069 
006A 
006B 


0003 
0000 
OOOF 
0000 
003E 
0000 
0043 
0000 
04D2 
C1C2 
0000 
0000 
0059 
0000 


R 
E 
R 
E 
R 
E 
R 
E 
A 
A 
E 
t 
R 




LPeSL 




62 








* 






63 








« 


THIS ROUTINE WILL OPEN A FILF | 


64 








« 






65 


006C 


C8BA 


A 




LDX 


•LIST6 



Figure 32. Monitor Service Routine Examples (cont.) 
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66 


006D 


75AI 


A 




RCPYI 


P#L 


epEK A File with sLecKiNc buffer 


67 


006E 
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A 




B 


^i:ePEN 


SPECTFIED eF LABFL PQ IS ALREADY 


68 


006F 
0070 
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D7D8 
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A 


LIST6 


DATA 


X»4000»* 'PQ' 


ASSIQMED Te FILE 


69 


0071 


0072 


R 




DATA 


BLOCKER 




70 


0072 






BteCKER 


RES 
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BUFFPR size for 720X RaD 


71 
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E 
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AN BPLABLE 
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75 
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C800 


A 




LDX 


»LIST7 




76 
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A 




RCPYI 


P#L 




77 


Ol?A 


4CCF 


A 




6 


MtASSIGN 


NAMEn HELLe IN USER PRSCESSOR 


78 


012B 


COOS 


A 


LIST7 


GENi2^ 


»10,4 3,0#5 




79 


012C 
012D 


D7D8 
0132 


A 

R 




DATA 


'PO»*TEMP 




80 


012E 


C8C5 


A 




DATA, 4 'HELLe ' 






012F 


D3D3 


A 












0130 


D6*0 


A 












0131 


40^0 


A 










81 
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RES 
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82 
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83 
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84 
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85 
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LDX 


-LIST8 




86 
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75AI 


A 




RCPYI 


P#L 


BRINn IN SEGMENT 1 AMD 


87 


01E8 


4C13 


A 




B 
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TRANsFEP CSNTReL T8 ITi 


88 


01E9 
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A 
A 
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DATA 


X»C001»* 'Pp 
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89 


OlEB 


0000 


E 
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eVlLOAD 


FftR BACKGReUND PRSGRAM 


90 
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91 
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92 
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93 
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Figure 32. Monitor Service Routine Examples (cont.) 
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7. HOW TO USE UTILITY 



The Utility Processor is a highly flexible collection of media operation routines composed of six primary functions: 
Copy, Dump, three Editors and a Control Function. Each function operates independently of the others but in con- 
junction with a root called the Utility Executive. The Executive scons the lUTILITY control command for param- 
eters and if none are found, it is assumed that only the control functions are desired by the user. 

The Control Function Processor consists of file and record positioning commands, pause and message commands, an 
assignment command, a write file mark command, and a prestore command. 

When a specific routine is requested, the Executive checks to see that it is available, reads it into core, and ini- 
tializes the required tables and flags. The Executive is used to process all utility control commands, which 
always read using the SI operational label. 



are 



The "prestore" function requires an additional explanation. Prestore is a condition wherein the control commands, 
or sometimes data, is "prestored" in a temporary file (X5) for later processing. The prestore function may be in- 
voked by control command (!*PRESTORE) or, under certain conditions, by the requested routine. Termination of 
the prestore function occurs when a !EOD, l*END, or file mark is encountered. The conditions under which pre- 
store is invoked will be discussed more fully in the description of the Utility routines. 

All of the Utility routines share the use of certain operational labels: SI, UI, UO, LO, DO, OC, and BI. Several 
functions will optionally accept user-supplied operational labels, and these cases will be described in the individual 
descriptions. 

Before going on to discussions and examples of the various functions, three points should be mentioned about the 
material covered in this chapter: 

• When using any of the functions for the first time, you should supplement the material in this chapter with 
study of the appropriate subchapter in the Utility section of the RBM Reference Manual (Chapter 9). 

• All Utility examples in this chapter show lASSIGN cards with device mnemonic operational labels instead 
of device file numbers in the device assignments. This is a SYSGEN-implemented capability that is rec- 
ommended where a number of intermittent users are on the system, and particularly if a large number of 
Utility jobs are being run. See Chapter 19, "How To Assign and Use Device Operational Labels" in this 
manual for more details. 

• In these examples, !EOD cards may be replaced by !*END cards. 



HOW TO COPY AND VERIFY 

The Copy routine is called by a lUTILITY COPY command to copy information from one device to another device 
and, optionally, to verify (compare) the copies. Note that RAD or disk pack files are also considered "devices". 

Copy requires a !*OPLBS command to define the output device(s). This command must precede any file positioning 
or processing commands, but must follow a l*PRESTORE command (if present), and may follow I *ASSIGN commands. 
Data to be copied is always input from the UI device. The UI assignment must be specified on an lASSIGN or 
!*ASSIGN command, if different from the SYSGEN assignment. The copies are output on the device (s) specified 
on the !*OPLBS command. A command string may contain more than one l*OPLBS command. In the verify func- 
tion. Copy uses opiabel X4 as one input, and the opiabel specified on the last prior !*OPLBS command as the 
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other input; or, data from X4 ts compared to an in-core buffer if the CORE parameter was used on the ! UTILITY 
COPY command. If UI and SI are assigned to the same device (or device file number, if the device is a RAD), SI 
is prestored. The number of records and files copied or verified is output to the DO device upon completion. 

HOW TO COPY CARD READER INPUT TO LINE PRINTER 

The example illustrated in Figure 33 will read one file from a card reader and list the contents of the file on 
the line printer. 



lEOD 



Copy input 




!EOD 



I *COPY F 



!*OPLBS LP 



! UTILITY COPY 



[ASSIGN UI=CR 



UOB 



J/ 



Figure 33. Copy Card Input to Line Printer 

The ! ASSIGN card assigns UI to the permanent operational label CR. Note that CR is a SYSGEN-defined label 
assigned to the file number (DFN) associated with the card reader. If device mnemonic operational labels were not 
implemented at the local facility, UI would have to be assigned to the DFN (e.g., 2) or another less-easily remem- 
bered operational label assignment to the card reader DFN. 



The lUTILITY COPY card calls in the Utility Executive and the Executive calls in the Copy routine. 
CORE option is not specified, a copy of the input will not be stored in core memory. 



Since the 



The !*OPLBS card specifies that the output device for the copy is to be the line printer (LP). At this point, the 
Copy routine determines if prestore should be invoked. Since the control commands (SI) and the Utilityinputs (UI) 
opiabels are assigned to the same device (card reader), prestore will be used. The control commands, through the 
first lEOD card, will be written on temporary RAD file X5. The control commands are now read and executed as 
though opiabel SI had been assigned to X5. 

The !*COPY card causes the records from the card reader to be written to the line printer until one complete file is 
copied (specified by the F parameter). If "R" was specified instead of "F", one record would be copied. The sec- 
ond lEOD card indicates end of file for the card reader inputs. The !EOD following the I *COPY card not only 
terminates prestore, but will cause Utility to exit when read from X5. 

If we had wanted to copy from paper tape (for instance) to the line printer, the lASSIGN card would be 
changed to read UI=PT, and the input would be followed by an !EOD (NL). Since SI and UI would be as- 
signed to different devices, no prestore would be used. 
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HOW TO COPY AND VERIFY FROM A RAD FILE TO PAPER TAPE 

In the example In Figure 34, the input to be copied on paper tape is located in a user-defined permanent RAD file 
called COPT in the UD (User Data) area. 



lEOD 



! *VERIFY F 



!*REWIND UI 



l*PAUSE LOAD PT TO VERIFY 



!*COPY F 



!*OPLBS PT 



[UTILITY COPY 



lASSIGN X4=COPT,UD 



{ASSIGN UI=COPT,UD 



IJOB 



Figure 34. Copy and Verify File from RAD Area to Paper Tape 

The first lASSIGN command defines the input "device" from which the data is to be copied as file COPT in the UD 
area of the RAD. The UI device must always be defined when using the COPY routine. This may be done either at 
SYSGEN or at run-time. 

The second lASSIGN card defines X4 to also be file COPT in the UD area. This card also causes adjustment of the 
byte count (from the COPT input) to 80 or 120 bytes before being copied to paper tape. The byte count depends on 
the contents of the first byte in the data to be copied. Note that non-standard binary can be copied to or from 
paper tape by specifying the byte count in the BIN mode on either the !*COPY or the l*VERIFY commands. See 
the COPY run-time discussion in Utility Chapter of the RBM Reference Manual. 

The !*OPLBS card specifies that the output device for the copy is to be paper tape (SYSGEN -defined device mne- 
monic operational label PT). 

The !*COPY card specifies that a file (F) is to be copied rather than a record (R), and by default, specifies that a 
single file is to be read. 

The !*PAUSE card causes the system to go into a wait state to give the operator time to rewind and load the paper 
tape output for verification. 

The !*REWIND UI card causes the RAD to "rewind" to the beginning of the file prior to the verify process. Since 
UI and X4 are assigned to the same device, the card could alternatively specify !*REWIND X4. 

The !*VERIFY card causes the two files to be verified (compared) to the end of one file (F). 

The lEOD card causes control to be returned to the Monitor. 
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HOW TO COPY MAGNETIC TAPE TO MAGNETIC TAPE 

The example In Figure 35 will copy and verify all files from one magnetic tape to another until a double end-of-file 
is encountered. 



!EOD 



!*UNLOAD Ml 



!*UNLOAD MO 



!*VERIFY F, ALL, 8 192 



!*REWINDM1 



!*REWIND UI 



!*COPY F, ALL,, 8192 



!*OPLBS Ml 



! UTILITY COPY 



1ASSIGNX4=M0 



{ASSIGN UI=MO 



IJOB 



Figure 35. Copy and Verify Magnetic Tape to Magnetic Tape 

The first two lASSIGN cords assign opibs UI and X4 to the same magnetic tape input device (MO). 

The !*OPLBS card defines Ml as the device that receives the copy output. 

The !*COPY card specifies that all files (ALL) are to be copied until a double EOF Is encountered, and the double 
comma specifies that the FORM parameter is not being used since no output is to go to the line printer or keyboard/ 
printer. Since we will, in this example, assume that the maximum record size is not known, the maximum permls- 
sable record size of 8192 bytes is specified. If any record read exceeded this maximum, a "CALLING SEQUENCE 
ERROR" message would be output and Utility would abort with a UT abort code. 

The !*REWIND UI (or !*REWIND X4) and !*REWIND UO will rewind the MO and Ml magnetic tapes in prepara- 
tion for verification. 

The ! *VERIFY cord causes the MO and Ml magnetic tapes to be read and compared. 

The two !*UNLOAD cards cause the tapes to be rewound and placed In manual mode. 

HOW TO COPY A FILE TO LINE PRINTER 

An example of how to copy the listing output from either an assembly or compilation to the line-printer is given In 
Figure 36. The input (UI) could be read In from a magnetic tape or compressed RAD file. 
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!EOD 

!*COPY F,,FORM 



!*OPLBS LP 



! UTILITY COPY 



lASSIGN UI=MYLO,UD 



!JOB 



Figure 36. Copy LO File to Line Prinl-er 



In this example, the lASSIGN card assigns UI to a compressed RAD file called MYLO located in the User 
Data area. 

The !*OPLBS card defines the line printer (LP) as the device to receive the copy, and the l*COPY card specifies 
by default (double comma) that one file is to be copied. The FORM parameter specifies that the first byte of each 
record is used for line printer or keyboard/printer format control and is not to be printed. 



HOW TO PRESTORE CONTROL COMMANDS 

The prestore mode separates control command functions from data when both are read in from the same input device, 
and then delays execution of the control commands until an !EOD is encountered. It does this by prestoring all 
Utility commands on a temporary RAD file (X5) up to an !EOD, and they are then executed in sequence to process 
the input data. 

When the Copy routine is being used, the Utility Executive will automatically prestore commands when SI and one 
or more other opibs are assigned to the same input device^ but you can "force" prestore through the use of a Utility 
!*PRESTORE card. 

In the example shown in Figure 37, a card deck is verified against a paper tape, with the data deck and control 
commands being read in from the same device. We will use the UO operational label as an input source to com- 
pare against X4. 

The first two lASSIGN cards assign SI (for PRESTORE input) and UO (for VERIFY output) to the card reader (CR de- 
vice operational label), and the third jASSIGN card assigns the X4 device to paper tape. 

The !*PRESTORE command (which must always follow the ! UTILITY card) causes all Utility control commands to be 
loaded into the X5 RAD file and delays their execution until the lEODcard following the IVERIFY card is read. 



Prestore takes place under different conditions in the Object Module Editor. See the OMEDIT subsection in 
Chapter 9 of the RBM Reference Manual. 
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!FIN 



Z 



!EOD 



Deck for comparison 




!EOD 



!*VERIFYF 



!*PAUSE LOADPT 



!*OPLBS UO 



LJL 



!*PRESTORE 



! UTILITY COPY 



!ASSIGNX4=PT 



lASSIGN UO=CR 



[ASSIGN SKR 



!JOB 



Figure 37. Verify Card Deck and Paper Tope with Forced Prestore 

The !*OPLBS cord defines UO as the output (in this case input) device, which is the card reader since UO was pre- 
viously assigned to CR. 

The !*VERIFY card causes card deck to be read from UO and compared with the data written on paper tape 
(X4). 

HOW TO USE UTILITY DUMP 

The Dump routine will dump (print) records or files from one media onto any device you specify. You can also 
specify whether the dump is to be in EBCDIC or hexadecimal format. Dump is called by a {UTILITY DUMPcommand. 
If an operational label is specified with this command, input is from the device assigned to that label; otherwise, in- 
put is from the UI device. Output is always to the LO device. The number of records may be specified by the first 
parameter on a l*DUMP command. If this parameter is blank, records will be dumped to a file mark. If the param- 
eter is ALL, records will be dumped to a double EOF. Maximum record size may also be specified. Input data may 
be binary or EBCDIC. If the HEX parameter is specified on the ! *DUMP command, the output is in the hexadecimal 
equivalent of the input (assumed binary). If HEX is omitted, records with a binary indication in the first byte (see 
the DUMP description in Chapter 9, RBM Reference Manual) are output in hexadecimal; all others ore assumed 
EBCDIC and are output as such. 

If SI and the input device are assigned to the same device or RAD DFN, SI is prestored. 
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HOW TO DUMP A MAGNETIC TAPE 

The deck example given in Figure 38 will dump a magnetic tope assigned to operational label Ml onto whatever 
device is assigned to LO (normally a line printer). 



!FIN 



!EOD 



!* DUMP ALL 



I UTILITY DUMP MT 



UOB 



Figure 38. Dump a Magnetic Tape 



The lUTILITY DUMP card calls in the Dump routine and specifies that input is to be read from MT. If an opib was 
not specified, input would be read by default from the device to which UI Is assigned. 

The !*DUMP card specifies that all records on the tape ore to be dumped until a double EOF is encountered (ALL). 
Since neither the "mode" or "size" are specified, the default options of EBCDIC format for the output and the stan- 
dard record size (120 bytes) will be used. 

HOW TO DUMP A RAD FILE 

The example given in Figure 39 will dump a user-defined sequential access RAD file called SAMP from the User 
Data area of the RAD. 



!EOD 



!*DUMP ,HEX, 12000 



lUTILITY DUMP 



lASSIGN UI=SAMP,UD 



!JOB 



Figure 39. Dump Sequential Access RAD File 
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The .'ASSIGN card assigns UI to file SAMP, in the User Data (UD) area of the RAD. 

The lUTILITY dump card calls in the Dump routine and specifies the input device as UI by default, which for 
the length of this one job, is temporarily assigned to the SAMP file in the UD area. 

The !*DUMP card causes the SAMP file to be dumped out to the LO operational label. The HEX parameter speci- 
fies the dump is to be in hexadecimal format and maximum size of the record to be dumped is 12000 bytes (which 
would probably be determined by looking at a RAD map). Note that since this is a sequential access file, themaxi- 
mum record size specified must be an even number. 



HOW TO USE THE OBJECT MODULE EDITOR 

Like the other two Utility Editors, the Object Module Editor generates or maintains (updates) magentic tape, paper 
tope, RAD, or disk pack files. As its name implies, OMEDIT works with binary object modules that are output from 
assemblies or compilations. 

OMEDIT is called by a lUTILITY OMEDIT command and itself has no specification parameters. OMEDIT oper- 
ates in two modes: list and modify, and either a l*LIST or !*MODIFY card must follow the lUTILITY OMEDIT 
card. 

In the list mode, object modules are input from the UI device, checksum and sequencing are checked, and the 
"ident" (the result of an IDNT directive in Extended Symbol or a subroutine name in FORTRAN) is printed on the 
LO device. Checksum and sequence errors are flagged on LO, and listing continues. 

In the modify mode, two alternatives are available: GEN and INSERT. If the GEN parameter is used, it must be 
followed by a ! *INSERT command. OMEDIT then copies binary records from BI to UO, performing checksum and 
sequence checks. 

If the INSERT parameter is used, it may be followed by !*INSERT commands or by !*DELETE commands. Binary rec- 
ords are copied from UI to UO. A !*DELETE card causes the named modules to be omitted from the UO records. The 
l*INSERT command causes modules from the BI device to be written, in sequence, to the UO device. The first ident 
on the !*INSERT command specifies the BI module to be inserted; the second ident, if present, specifies the UI mod- 
ule it is to follow. If the second ident is absent, the BI module will be the next module written to UO. 

Prestoring of control commands or binary data will occur under the following conditions: 



Opiabels 


Assi 


igned 


to 




the Same 


De^ 


/ice 


— 


Prestored 


SI,BI 








SI 


SI,UI 








SI 


BI,UI 








BI 


SI,BI,UI 








SI,BI 



OMEDIT will not terminate and exit until two successive lEODs are encountered from UI or BI. 



HOW TO LIST OBJECT MODULES FROM GO FILE 

The example in Figure 40 will read the object module(s) located on the default GO file (RBMGO) from the System 
Data area of the RAD, and list the contents until a double !EOD is encountered. 
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!EQD 

!EOD (or !*END) 



!*LIST 



! UTILITY OMEDIT 



lASSIGN UI^BMGO,SD 



UOB 



Figure 40. List Object Module from RAD File 



The lASSIGN card assigns UI to the RBMGO file, and the !*LIST card will cause the contents to be listed on 
the LO device (normally the line printer). 

HOW TO UPDATE OBJECT MODULES FROM CARDS 

The example in Figure 41 will read in a set of update modules (BI) that modify the original binary obiect modules 
(UI). The updates, original modules, and control commands are all read in from the same device. The updated 
version of the program is to be written on magnetic tape. Since BI (updates) and UI (old modules) are assigned to 
the same device (SI), the complete BI file will be automatically prestored on a temporary RAD file before the up- 
date takes place. All inserts and I *INSERT commands must be in the proper sequence. 



!*INSERT CHANGE,INP 



!*DELETE OUTP 



!*INSERTSTEP,CALC 



l*MODIFY INSERT 



lUTILITY OMEDIT 



lASSIGN UI=BI 



lASSIGN UO=MT 



UOB 



Figure 41. Update Object Modules from Card Reader to Magnetic Tape 
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UI Object 

Modules To 

Be Updated y 



zz 



!EOD (or !*END) 



!EOD 



(Old) MOD Object Module (replaced) 



INP - Object Module 



OUTP Object Module 




UI Object 
Modules To 
Be Updated 



/I 



V 



CALC BI Object Module 




!EOD 



zz 



BI Update 
Modules 



/z 



(New) MOD Object Module 

/ ' 

CHANGE Object Module 



STEP Object Module 




!EOD 



!*DELETE MOD 



!*INSERTMOD 



y 



Figure 41. Update Object Modules from Card Reader to Magnetic Tape (cont.) 
The deck structure in Figure 41 will perform the following functions: 

1. Insert module STEP after module CALC. 

2. Delete module OUTP. 

3. Insert module CHANGE after module INP. 

4. Insert "new" module MOD after module CHANGE. 

5. Delete "old" module MOD. 

6. Write updated version on magnetic tape assigned to UO. 
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The card images of the resulting updated version of the program written on magnetic tape would appear as shown 
in Figure 42, as compared to the UI version shown in Figure 41. 



/ 

(New) MOD Object Module 



CHANGE Object Module 



/I 



/I 

INP Object Module 



zz: 



STEP Object Module 



CALC Object Module 




_y 



y 



Figure 42. OMEDIT Update Example 

HOW TO USE THE RECORD EDITOR 

The Record Editor edits FORTRAN or assembly language source input by record number in the following manner: 

• Generates source data files. 

• Lists source data files with associated line numbers. 

• Modifies source data files. 

A !*LIST command places RECEDIT in the list mode. Source files are read from UI and listed on LO, with asso- 
ciated line numbers starting with "1". An lEOD or file mark will cause line numbering to restart with 1. An op- 
tional "number" parameter on the !*LIST command indicates the number of files to be read; if "number" is omitted, 
one file will be read. If double I EODs are encountered, the list mode is terminated. 

The !*MODIFY command initiates the modify mode ( and will terminate the list mode). The GEN parameter on this 
command causes source images to be copied from SI to UO. If the LIST parameter is also present, UO and the asso- 
ciated line numbers will be listed on the LO device. 

If the GEN parameter is absent, updating is implied. If LIST is present, the LO listing will contain the UI line 
numbers. In the update mode, UI is read, modified by control commands and source images from SI, and written 
to UO. Lines specified by number on a !*DELETE command are omitted from UO. 

Source images following (on SI) an !*INSERT command are written on UO following the UI line number that 
is specified on the ! *INSERT command. A source image following a !*CHANGE command replaces the UI 
source image whose number is specified on the !*CHANGE command. If more than one source image follows 
the ICHANGE card, those following the "changed" one are inserted before the next UI image is copied. Two 
numbers on the !*CHANGE command causes deletion of all UI images inclusively between the numbers. Source 
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images on SI following either !*INSERT or !*CHANGE commands are inserted on UO until the next control 
command is encountered. When a lEOD is encountered from SI, the remainder of the UI file is copied to UO. 



If SI and UI are assigned to the same device, SI is prestored. 



It is worth mentioning that assembly language users have some record editing functions available to them through 
the assembler. See the specification options on the IXSYMBOL control command in the Extended Symbol/LN, 
OPS Reference Manual, 90 10 52, for record updating capability. 



HOW TO LIST A SPECIFIED FILE FROM MAGNETIC TAPE 

The example given in Figure 43 would list the sixth file from a magnetic tape. 



!EOD 



l*REWINDUI 



!*LIST 



! UTILITY RECEDIT 



iPSKIP UI,5 



lASSIGN UI=MT 



UOB 



Figure 43. List Specific File for Magnetic Tape 



The lASSIGN card assigns UI to the MT operational label for a magnetic tape, and the IFSKIP card causes UI to 
be skipped past the first five EOF marks. 

The !*LIST card then causes all records in file six or the UI tape to be listed until the next EOF is encountered 
and UI is then rewound. 



HOW TO MODIFY A SOURCE MODULE TO A RAD FILE 

The example in Figure 44 will read source record updates, the original source deck, and all control cards from the 
card reader. The updated source module will then be written in a compressed, blocked RAD file called MYSORS 
(user-defined) In the User Data area. Prestore will be imposed since SI=UI. 

The !*MODIFY card specifies that both the records deleted and the records inserted will be listed on LO, including 
UI line numbers deleted and the line number preceding the one inserted. Since updating is to be performed, the 
GEN parameter must not be present on the card. 

The l*DELETEcard specifies that lines 31 and 32 are to be deleted from the source records, and the !*INSERT card 
specifies that source records are to be inserted after line 49. In our example, four new records are inserted. 
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!EOD 



Oriflinal Source Module 




!EOD 



New Source Record 2 



*- New Source Record 1 



New Line 54 



!*CHANGE54 



Source Record 4 



Source record 1 



!*INSERT49 



!*DELETE 31,32 



!*MODIFY LIST 



lUTILITY RECEDIT 



lASSIGN UO-MYSORS,UD 



lASSIGN UI=CR 



!JOB 



Figure 44. Update Source Records in Source Module 



The !*CHANGE card specifies fhat- line 54 is to be replaced and that new source records may be inserted after the 
new line 54. In this case, two new records are inserted. 

HOW TO USE THE SEQUENCE EDITOR 

SEQEDIT performs the same functions and operates similarly to RECEDIT; the principal difference being that SEQEDIT 
operates on sequence numbers In the sequence field of the source image (columns 73-80 of a source card), thus pro- 
viding more flexibility than RECEDIT. Again, source is read from UI, modified by commands and source data from 
SI, and the update is written to UO. SEQEDIT is not recommended for paper tape use. 

SEQEDIT is called by a lUTILITY SEQEDIT command. Three optional parameters are allowed on the call: 
GEN, IGN, and ALL (in that order). The GEN parameter specifies that the source Is copied from SI to UO. 
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The absence of GEN implies UPDATE mode. The IGN parameter indicates that sequence errors are ignored 
on SI if in GEN mode, or UI if in UPDATE mode. The presence of the ALL parameter causes SEQEDIT to con- 
tinue until double lEODs are encountered. 

A special command !*IDENT is available to break the sequence field into an "ident" and a numerical section. 
This facilitates updating of multiple files or multi-program files. 

Insertions and replacements are accomplished by the source images (on SI) themselves, rather than by specific com- 
mands. If an image on SI has the same sequence field as an image on UI, the SI image is written to UO instead of 
the Image from UI. If an SI image has a sequence number between two UI images, the SI image will be inserted, on 
UO, between those two UI images. If SI contains a block of images with blank sequence fields that follows an image 
with a sequence number, UO will contain the numbered image (be it insertion or replacement), followed by the 
blank-sequence images. 

Deletion of images from UI is accomplished by a I *DELETE or a !*SUPRESS command that contains the sequence num- 
ber to be deleted. If two numbers are present, UI images will be deleted inclusively between the numbers. The 
difference in the two commands is that ! *DELETE causes the deleted Images to be listed on LO while !*SUPRESS 
does not. 

The !*SEQUENCE command may be used to sequence a file being generated, or to resequence files being updated. 
If multiple files are being updated, a new !*SEQUENCE command must be used for each file. 

If UI and SI are assigned to the same device, SI is prestored. 



HOW TO GENERATE AND SEQUENCE A FILE ON MAGNETIC TAPE 

The job example In Figure 45 will generate and sequence a new file on magnetic tape. 



The {UTILITY SEQEDIT card specifies that a single file Is to be generated on UO, and the presence of the GEN pa- 
rameter also informs the Sequence Editor that no updates are to take place. (Updating and generation cannot take 
place within the same call to the Sequence Editor.) IGN indicates that SI sequence errors are to be ignored. 



!EOD 



Deck 




!*SEQUENCEUT,100 



lUTILITY SEQEDIT,GEN,IGN 



! ASSIGN UO=MT 



lASSIGNSKR 



!JOB 



y 



Figure 45. Generate and Sequence a File on Magnetic Tape 
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The !*SEQUENCE card specifies that UT is the ident field and that the sequence numbers ore to be in increments 
of 100. This will permit a large number of later insertions without interfering with the original sequence numbers. 
Thus, the first sequence number would appear as UTOOOIOO, the second number as UT000200 and so on. The se- 
quencing will take place as the file is being generated. 



HOW TO UPDATE AND RESEQUENCE TWO FILES ON MAGNETIC TAPE 

The example in Figure 46 will update and resequence two separate files on a magnetic tape and write the updated 
versions on a new magnetic tape. 



z 



!EOD 



CP Update 




!*SEQUENCE CPOOOOIOJOO 



CP000010 



PK Update 




!*SEQUENCE PK000010J00 



PKOOOOIO 



!*IDENT2,6 



! UTILITY SEQEDIT ,,,ALL 



! ASSIGN UO=M2 



lASSIGN UI=M1 



lASSIGN SI-CC 



UOB 



Figure 46. Update and Resequence Two Magnetic Tape Files 



The first [ASSIGN card assigns SI to CC, which defines the device from which the updates and control commands 
will be read. The next two lASSIGN cards assign Ml as the device from which to read the two files to be updated, 
and M2 as the output device to write the updated and resequenced version. 

The triple comma on the lUTILITY SEQEDIT card specifies that the GEN,IGN options are not being exercised, and 
the ALL option specifies that updating is to continue until two EOFs are encountered on the UI device (Ml). 
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The !*IDENT card, used only when updating files, specifies that the number of characters in the ident portion of 
the sequence field is two characters, and the 6 specifies the number of characters in the sequence number subset of 
the sequence field. The card holds true for both updates. 

The first !*SEQUENCE specifies that resequencing will begin when a card containing PKOOOOIO in columns 73-80 is 
found, and that resequencing will be in increments of 100, beginning with PKOOOOIO (if the increment number was 
missing, the increment would be 10 by default). The "PKOOOOIO" parameter (in columns 73-80) specifies the se- 
quence number at which the resequencing is to commence to incorporate the update. 

The PK update will be added to the original file beginning at sequence number PKOOOOIO, and all line numbers 
from that point will be in increments of 100 (e.g. , PKOOOllO, PK000210, etc). 

The second !*SEQUENCE card causes identical functions to be performed with the CP update. 
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8. HOW TO INTERFACE ANS FORTRAN IV AND EXTENDED SYMBOL SUBROUTINES 



This chapter defines the conventions and techniques required for interfacing Extended Symbol and ANS FORTRAN IV 
programs and subprograms with one another and with FORTRAN Library routines. The material attempts only to 
clarify those points directly related to interface problems, and more detailed coverage of the items discussed will be 
found in the appropriate language reference manuals listed in "Related Publications". It is assumed that you are 
already conversant with the use of the language processors. Loaders, and characteristics of the library routines that 
are available on your system. 

GENERAL CONCEPTS AND CONVENTIONS 

EXTERNAL REFERENCES 

Separately assembled or compiled program sections or library routines may refer to symbolic locations within other 
sections via external references. In Extended Symbol, this is accomplished with the DEF and REF directives. A 
DEF "name" declares that the value of "name" is accessible to the outside world. A REF "name" implies that the 
value of "name" is to be obtained from another program section and is to replace all references to "name" within 
this section. In particular, if "name" is a DEF within a selected library, the REF will cause that library routine 
to be loaded as part of the program. Since, during loading, the value of the "name" is its location, this means 
that the location of the name will replace the references to "name". 

In FORTRAN, a DEF is implied in a SUBROUTINE or FUNCTION subprogram, where "name" is the name of the 
subroutine or function. A REF is created either by the explicit "CALL name (x)", or by the use of a function name 
within an expression (e.g., A = name (x)). Additionally, if "name" appears in an EXTERNAL statement, all ref- 
erences to "name" will result in the creation of a REF. 



TEMPORARY STACK 

When operating in a priority-interrupt environment, it is essential that a routine that might be used concurrently by 
different tasks (i.e., interrupt levels) is coded reentrantly. To achieve reentrancy, the called routine must not 
store call -dependent data values within itself at fixed locations. The method adopted by Sigma 2/3 standard soft- 
ware is for the program calling a reentrant routine to provide a certain amount of scratch storage for any storage the 
reentrant routine may require. This is called a temp stack, and it is expected that the calling program will make 
available the start address of its own temp stack before calling the reentrant routine. To provide for this structure, 
ANS FORTRAN IV is careful to ensure that the temp stack does not attempt to contain any preset data. (See also 
Chapter 14 of this manual for a detailed explanation of temp stack and assembly language reentrancy.) 

Any variables (scalar or array) that appear in a DATA statement in an ANS FORTRAN IV program or subprogram will 
be allocated within the body of the program along with the code. All other variables are allocated in the temp 
stack. This technique has no impact on nonreal-tlme programs. However, it does allow the real-time programmer 
to have "named constants" within his program. An example of an occasion where the named constant concept is vol - 
uable is where the routine is to be parameterized. If this "constant" variable is used in lieu of an actual constant, 
it is possible to easily alter the control. 

Real-time programmers may elect to use variables that have been preset as other than "named constants". Any such 
usage must be done with extreme caution. 

FLOATING ACCUMULATOR 

The Floating Accumulator is simply a name for the first six cells in a calling program's temp stack. Since various 
routines employ temp storage for different purposes, this convention should not be thought of as an actual area used 
only for floating-point calculations. Within a sequence of floating operations, however, it is treated much like 
the A-register in Sigma 2/3 class 1 instructions. 
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COMPLEX ACCUMULATOR 

In order to handle the computation of complex arithmetic functions, ANS FORTRAN IV has introduced the Complex 
Accumulator. The Complex Accumulator is the name for the n + 4 to n + 15 cells of the portion of the temp stack 
that is reserved by a FORTRAN Main program. The location of this area is held in the n + 3 cell of the Main pro- 
gram, and is passed to each FORTRAN program that is called. 



BLANK COMMON STORAGE 

The Overlay Loader provides for both program-relocatable and blank COMMON-relocatable load items. Note that 
the Loader will not actually place data into blank COMMON storage, but will resolve address references relative 
to a specified COMMON base. It is often desired to share COMMON storage between FORTRAN and Extended 
Symbol. Its use should be made clear by the example below, which defines identical COMMON areas: 



FORTRAN 



COMMON DAT1(10,20),TEMP(20),ICNT,ITEMP(5),MOD 



Extended Symbol 

(Assume above compilation uses the standard XDS allocation) 



INTSIZE 
REALSIZE 



EQU 
EQU 



INTEGER WORD SIZE 
REAL WORD SIZE 



DATl 

TEMP 

ICNT 

ITEMP 

MOD 



COMMON REALSIZE*(10*20) 
COMMON REALSIZE*(20) 
COMMON INTSIZE 
COMMON INTSIZE*(5) 
COMMON INTSIZE 



400 LOCATIONS 
40 
] 

5 
1 



Blank COMMON is discussed in detail in the chapter "How to Build An Overlay Program" earlier in this manual. 

NAMED COMMON STORAGE 

ANS FORTRAN IV has introduced an additional form of named COMMON that is available for use by both the 
FORTRAN and Extended Symbol programmers. An Extended Symbol program may reference named COMMON 
that is defined in a FORTRAN program. In general, the Extended Symbol access to a named COMMON is roughly 
equivalent to the technique that would be used to access locations within an Extended Symbol routine that has 
only its first location DEF'd. The example below shows the general form of the technique to be used: 



FORTRAN 



COMMON/ALPHA/DAT9,TEMPA(20),TEMPB(300),TEMPC(2) 



Extended Symbol 



REALSIZE 


EQU 


2 


DAT9 


EQU 





TEMPA 


EQU 


D 



REAL WORD SIZE 



DAT9+REALSIZE 
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TEMPB 


EQU 


TEMPA+(20*REALSIZE) 


TEMPC 


EQU 


TEMPB+(300*REALSIZE) 


LDX 


= ALPHA 




LDA 


DAT9J 




LDX 


= ALPHA 




LDA 


TEMPAJ 




LDX 


= ALPHA 




LDA 


TEMPA+(9*REALSIZE),1 


LDX 


= ALPHA 




LDA 


= TEMPC 




RADD 


A,X 




LDA 


0,1 





TEMPA(l) 



TEMPA(IO) 



TEMPC (1) 



CODING EXTENDED SYMBOL ROUTINES FOR CALLS FROM FORTRAN 

Both SUBROUTINE and FUNCTION subprograms maybe coded In assembly language for subsequent call by a 
FORTRAN program. The name(s) identifying the entry point(s) to the routine is (are) declared in a DEF 
directive. 



STANDARD CALLING SEQUENCE 

FORTRAN generates the following code when a SUBROUTINE coll or FUNCTION reference occurs: 



REF 


name 


RCPYI 


P,L 


B 


name 


DATA 


X'n' 


ADRL 


arg. 



ADRL 



argument keyword 
one entry for each 
actual argument in the call 



arg, 



The "argument keyword" specifies the addressing mode of each argument address. It consists of 1-8 two-bit codes 
such that bits 0-1 refer to argi, 2-3 to arg^, etc. More than eight arguments in a call will have an argument key- 
word preceding each group of eight argument addresses. The two-bit codes have the following meaning: 

00 - no more arguments (refers to argument k+1, which is nonexistant). 

01 - absolute address (the ADRL contains the actual address of the argument). 

10 - indirect relative address (the ADRL value, added to the present contents of the B-register, gives the ad- 
dress of the argument). 
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RCPYI 


PJ 


B 


*$+3 


DATA 


n 


ADRL 


TEMP 


ADRL 


MrPUSH 



11 -relative address (the ADRL value, added to the present contents of the B-register, gives the actual 
address of the argument). 

These codes have been covered in detail here because they will be used extensively in following subsections 
of this chapter. 



ARGUMENT TRANSFER ROUTINES 

There are several argument transfer routines available in the FORTRAN Library to relieve the Extended Symbol pro- 
grammer of the necessity for deciphering these calling sequences. The most general routine, MrPUSH, will be 
covered here. The other routines are, in general, subsets of MtPUSH and may be used as the application warrants. 
Essentially, MrPUSH does the calculations necessary to produce an absolute address for each of the arguments in the 
call, and moves these new addresses into a specified temp stack for easy accessibility in the called routines. 

The calling sequence for MrPUSH is 



(number of words to reserve) 
(address of temp stack) 



where n is equal to three plus the number of argument addresses (r) that will be converted and passed into the temp 
stack from the calling parameters, plus the number of temporary cells needed by the routine. MrPUSH exits with 
the A-register unchanged, the entry contents of the B-register in location TEMP+1, and the return address (calcu- 
lated from the number of arguments and the entry contents of the L-register) in location TEMP+2. In locations 
TEMP+3 to TEMP+3+n-l will be the absolute addresses of the calling arguments- The B-register will point to loca- 
tion TEMP. The E-register contains the number of arguments processed by MrPUSH upon return. 

It should be noted that the alternate entry point MrPUSHC must be used if the Extended Symbol routine Is to call 
(directly or indirectly) another FORTRAN routine. The MrPUSHC entry operates the same as the M-.PUSH entry 
with the exception that Ji must be equal to four plus the number of argument addresses. TEMP+1 and TEMP+2 have 
the some contents as for MrPUSH. TEMP+3 contains the address of the complex accumulator (obtained from the 
calling routine). Locations TEMP+4 to TEMP+4+n-l will contain the absolute addresses of the calling arguments. 



SUBPROGRAM EXIT 

The call to MrPUSH or MrPUSHC is normally placed as early in the subprogram as possible. Care must be taken 
to preserve the entry value of the L-register upon calling MrPUSH. Exit from a subprogram that used MrPUSH or 
MrPUSHC is effected simply by 

B MrPOP RETURN TO CALLING PROGRAM 



TEMP STACK DEFINITION 

The recommended method for terminating the source code of a subprogram is 

LPOOL DROP ANY LITERALS 

RES n SET UP TEMP STACK 

END NO TRANSFER ADDRESS 
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Note that "TEMP" and "n"are the same as in the call to M:PUSH. The LPOOL is included as a safety measure 
because no data can follow the temp stack if the program is to be converted to use dynamic storage. If this routine 
is placed in the Public Library by the Overlay Loader, the call to MrPUSH will automatically be changed to indi- 
cate dynamic temp allocation, and the trailing temp stack will be removed from the subprogram. 

ARGUMENT CHECKING 

MrPUSH ensures that the calling argument list is at least no larger than the n-3 locations allocated for it by the call 
to MrPUSH. More arguments cause a PU abort code. However, the subprogram may well be interested in whether 
there are less than the specified number of arguments in the call. Note that the L-register, upon entry to the sub- 
program, contains the address of the first argument keyword. Thus, to check for a minimum of three arguments, we 
might code 

RCPY L,X 

LDA 0,1 GET KEYWORD 

AND =X'0CO0' CHECK THIRD KEY 

BAZ ERROR ERROR IF ABSENT 

A FUNCTION subprogram makes use of the same techniques, the only difference being that a meaningful result must 
be left in the A-register and/or the Floating Accumulator upon exit. Conventions associated with such math routines 
are covered In the next subsection. 



CALLING MATH LIBRARY ROUTINES FROM EXTENDED SYMBOL 

Often a FUNCTION or SUBROUTINE subprogram coded in Extended Symbol will need to make use of the floating- 
point and I/O routines In the Math Library. These routines may be grouped In three main classes with regard to the 
calling and usage conventionsr Math routines. Arithmetic routines, and I/O routines. 

The address modes that are used In the reference of parameters may be classified as followsr 

TYPE 1 01 Keyr direct (or absolute) address. 

Type 1 data refers to constants that are incorporated directly In a program. They should never be 
altered by the program, and are referenced as Type 1 only by the program in which they are assem- 
bled. COMMON variables may not be assembled into the program but are addressed as Type 1 
data. 

TYPE 2 10 Keyr indirect, base-relative address. 

Type 2 address references are those made to subprogram dummy variables. In this case, MrPUSH has 
moved the addresses of the calling program's data into the subprogram's temp stack. 

TYPES 11 Keyr base-relative address. 

Type 3 data refers to non-blank-COMMON variables used within a given program. Variables should 
never be given initial values at assembly time, but Instead should be initialized at execution time by 
moving Type 1 data into the subprogram's temp stack. (Blank COMMON variables must be initial- 
ized at execution time. ) 

The above conventions ensure the reentrancy of any subprogram that may be used in a real-time environment. 
Note that the DATA statement In FORTRAN sets up Type 1 data, but allows this data to be modified at execution 
time. A FORTRAN subprogram should thus avoid ever modifying an Item declared in a DATA statement if it Is to 
be used in a reentrant mode. FORTRAN reentrancy is further discussed in Chapter 17. 
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MATH ROUTINES 

The calling sequence for a Math routine is the same as that used for standard function references. All registers, with 
the exception of the B-register, should be assumed to be volatile. The result will be returned in the Floating 
Accumulator. 



ARITHMETIC ROUTINES 

Although Math routines may be called with several arguments and thus use the keyword for address resolution, an 
Arithmetic routine expects at most one argument, and the address resolution Is specified by selecting the appro- 
priate entry point to the routine. The second argument of an Arithmetic routine is expected to be in the Float- 
ing Accumulator. 

The call to an Arithmetic routine is of the form 

RCPYI P,L 

B p:IDn 

DATA argument 

RETURN 
where 

p is L for standard precision. 

X for extended precision. 
:ID is the base name of the routine, 

n is 1, 2, 3, or 4, and corresponds to the address type of the argument. 



Each Arithmetic routine except p:33CPn (real compare) increments the L-register one location past the return ad- 
dress before returning. This allows consecutive calls on Arithmetic routines with only an initial RCPYI P,L. 
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9. HOW TO USE STANDARD PROCEDURE |S2| FILES 



A Standard Procedure (S2) file is an easy-to-use mechanism for allowing common symbols and often-used procedures 
to be stored in a special format so that they can be used automatically during an assembly, without being duplicated 
in each source program that uses them. 

A basic set of procedures that define the Sigma 2/3 machine instructions are supplied with the Extended Symbol as- 
sembler. This set of procedures should be considered a minimal base upon which to build other installation-specific, 
or user and program -specific S2 files. There is no limit to the number of S2 files you may have on a system. How- 
ever, RBMS2 is the only default S2 file and therefore does not need an {ASSIGN card. ({ASSIGN cards are re- 
quired for all other S2 files. ) 



WHAT MAY BE STORED IN AN S2 FILE 

There are two logical portions of an S2 file: the assembler's global symbol table, and the skeleton ("sample") pro- 
cedure definitions. These form the initial symbol and sample table areas within the assembler. Additional symbols 
and procedure definitions are added as they are defined in the source program. 

Any procedure definition may be stored in an S2 file. It may contain LOCAL directives, calls on other procedures 
defined in the same S2 file, or even calls on procedures that will be defined later in the source program that uses 
this S2 file. In general, anything that may legally occur within a CNAME, PROC, . . . , PEND group will be 
correctly stored on an S2 file. 

Some care must be taken in storing Main program global symbols (and their values) on an S2 file, but the resulting 
convenience is often as great as that of common procedure definitions. Likely candidates for standard S2-defined 
symbols are register designators and Zero Table constant identifiers. Such constants should be defined as absolute 
values via the EQU directive. In following the two rules itemized below, such symbols should not be placed within 
procedures in order to save core storage. A global definition such as, A EQU 7, will require six cells of storage if 
its definition is invoked by a procedure name, but will require only two cells if left at the Main program level when 
creating the S2 file. 

• Symbol values (at Main program level) stored on an S2 file should not be redefined by the source, nor 
should any attempt be made to store Main program-level LOCAL symbols on an S2 file. 

• No symbols stored on an S2 file should be used as arguments in a DEF, REF, or SREF directive (unless 
within a procedure definition). 

The action of the assembler is unpredictable if the above rules are violated. 

In summary, any legal procedure definition may be stored on an S2 file as may any unredefinable, nonexternal, 
global symbol value. A code-generating program should not be used to create an S2 file if the code generation 
occurs during creation of the file. 



HOW TO CREATE AN S2 FILE 

It is not possible to read in an existing S2 file, add to it, and create a new S2 file. For this reason it may be de- 
sirable to at least keep a source copy of the Sigma 2/3 instruction procedure set on bulk storage (RAD or disk pack). 
If a listing of this file is obtained at SYSLOAD time, it may be posted (or distributed) so as to serve as a base for 
special S2 files. The example in Figure 47 illustrates one method of preserving the source during SYSLOAD. 
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!EOD 



z 



END 



Source deck 




SIGMA 2/3 INSTR. PROCS. 



IXSYMBOL PP, LP 



! ASSIGN X1=RBMS2SI,UD 



!EOD 



FADD UD, RBMS2SI,,4,C, R 



IRADEDIT 



!JOBC 



ASSUME 'SY' 



y 



Figure 47. Save Instruction Procedures During SYSLOAD 



This example creates the standard (default) RBMS2 file and saves the source in a file called RBMS2SI in the User 
Data area. (XI is a copy of the source and is normally used only for the assembly listing). 

Assuming that the above procedure was used, the example in Figure 48 shows how a new S2 file is created using 
RBMS2 as a base. (Also assume that the listing from the example in Figure 47 showed the last line before the END 
line to be line number 90. ) 



lASSIGN S2=MY$PROCS,UD 



! ASSIGN SI=RBMS2SI, UD 



!#END 



li^ADD UD, MY$PROCS, 40, 108, B, R 



IRADEDIT 



IPAUSE KEY-IN SY,S 



IJOB 



Figure 48. Create An S2 File 
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z 



+END 



Source deck 



SOURCE FOR MY$PROCS 




+90 



IXSYMBOL UI, PP, LO 



Figure 48. Create An S2 File (cont.) 



The example in Figure 48 causes the source from RBMS2SI to be read, the source for the new procedures to be 
inserted immediately before the original END line, and the resulting set of procedures written to the MY$PROCS 
file in the User Data area. Note that MY$PROCS has been created using a blocked file with a record size of 
108 bytes, which is the required format for S2 files. Subsequent assemblies using this new file might be done as 
shown in Figure 49. 



Z 



I/END 



END 



Main Program 




MAIN PRGM USING 'MYPROCS' FILE 



IXSYMBOL LO,CR 



<- 'ASSIGN S2=MY$PROCS,UD 



UOB 



y 



Figure 49, Assemblies Using S2 File 



The lASSIGN card in Figure 49 prevents the automatic assignment of S2 to the default RBMS2 file. 
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The following update packet illustrates legal usage in creating an expanded S2 file: 
+90 

: OPERATIONAL REGISTER EQUATES 
Z EQU ZERO 

P EQU 1 PROGRAM 



E 

A 

* 

K:X8000 
K:X4000 

K:M15 

K:M16 

* 

BAL 



XR 



+END 



EQU 6 EXTENSION 

EQU 7 ACCUMULATOR 

: MONITOR CONSTANTS 

EQU X'09' X'8000' 

EQU X'OA' X'4000' 



EQU X'33' 

EQU X'34' 

: PROCEDURES 

CNAME 

PROC 

RCPYI P, CFR(2) 

B AFR(1),AF(2),AF(3) 

PEND 



X'FFFl' 
X'FFFO' 

BRANCH AND LINK (TO SUBROUTINE) 



CNAME 

PROC 

REOR 

REOR 

REOR 

PEND 



EXCHANGE REGISTER 



AFR(1),AFR(2) 

AF(2),AF(1) 

AF(1),AF(2) 



The above packet defines Z - A as standard symbols denoting operational registers, various symbols for standard 
zero-table constants, and a set of user-defined procedures such as BAL, A SUBRNAME, which loads a return address 
into the A-register and branches to "SUBNAME"; or XR T, A, which exchanges the contents of the T and A-registers 
without altering the condition codes. 
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10. HOW TO REDUCE ASSEMBLY LANGUAGE HARDWARE REQUIREMENTS 



The standard RBM processors make certain assumptions about resource allocation, and they operate most efficiently 
when these assumptions are met. A well -planned installation will provide these resources in the majority of in- 
stances, but exceptional problems can sometimes be accommodated within the existing resources via special 
techniques. 

The common resource constraints are either fast core storage, or bulk (RAD or disk pack) storage. In the cose of 
Extended Symbol, these two constraints are related, since this assembler uses several blocked files on bulk storage 
that require blocking buffers in fast core for each blocked file. Assuming that Extended Symbol is loaded with the 
standard blocking buffer parameters, an IXSYMBOL call will cause m*n words of fast core to be reserved for I/O 
buffers, where 

m = blocking buffer size = 180 for a 720X RAD-only system. 

= 512 for a disk-pack-only, or a mixed RAD/disk pack system. 

n = the number of the following operational labels that are currently assigned to blocked files: 

SI, UI, SO, LO, GO, BO, XI, X3, S2, DO 

Unless reASSIGNed, the GO, XI, X3, and S2 files are assigned to blocked files by default. In addition, the X2 
file requires a buffer that must be the size of a sector of the device to which the X2 operational label is assigned. 
On a disk-pack-only system, this would immediately remove over 2500 words from Extended Symbol's working stor- 
age (enough for assembly of approximately 2000 additional lines of program). Unless noted otherwise, the techniques 
given below apply to minimizing core storage requirements. Some consideration is also given to situations where 
such file elimination might be inadvisable. 

COPING WITH EXISTING RESOURCES 

Without modification of a program, the only improvement in resource demands during an assembly will be achieved 
by cutting down on the number of RAD/disk pack files and their associated blocking buffers. 



GO FILE ELIMINATION 

The GO file has a default blocking buffer, and is probably the safest to eliminate. If you have a suitable binary 
file output device such as magnetic tape, high-speed paper tape, or card punch, it may be feasible to bypass binary 
output to RAD or disk pack. The command 

JASSIGN GO=0 



saves a blocking buffer whether binary output is requested or not. If binary output is required, the following cards 
are recommended for saving RAD and buffer space: 



IXSYMBOL BO, 



lASSIGN BO=device 



{ASSIGN GO=0 
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XI FILE ELIMINATION 

The XI file has a default blocking buffer and is used by Extended Symbol to maintain a copy of the source (with 
possible updates) for listing purposes. If you are not using the update feature of Extended Symbol, it may be pos- 
sible to eliminate the XI file. If you have magnetic tape and the one or more source programs are separated by 
file marks on the tape, the following commands will eliminate XI and its buffer: 




In the case where your source program is already on a RAD/disk pack file, it is still possible to assemble this one 
program and eliminate XI. This may be done as follows: 



IXSYMBOL options 



lASSIGN X1=SI 



'ASSIGN SI=file name, area 



X3 FILE ELIMINATION 



The X3 file has a default blocking buffer, but this file is only used if the source program uses LOCAL directives at 
the main-program (i.e., not within a PROCedure) level. If it is known that a program does not use main-level 
LOCAL symbols, the IXSYMBOL command should be preceded by 

lASSIGN X3=0 



It is not necessarily a good practice to avoid main-level LOCALs however, since their use can generally reduce 
resource requirements more than their avoidance (see, "Coding for Existing Resources" in this chapter). 



S2 FILE ELIMINATION 

The final file with a default blocking buffer is S2. The S2 file should be left assigned to RAD/disk pack if at oil 
possible. While the procedure for running S2 from paper-tape, cards, etc. is easy to perform, the method is 
highly dependent upon the particular hardware configuration. 
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REDUNDANT FILE ASSIGNMENTS 

In general, unnecessary or redundant assignment of assembler files to RAD or disk pack should be avoided. This 
precept includes assigning unused default files to device zero. A redundant assignment would include something 
like assigning BO=GO, or DO=LO, where GO and LO were assigned to RAD/disk pack files. 

CODING FOR EXISTING RESOURCES 

There is an upper limit to the size of a program that may be assembled in a given system configuration. In Extended 
Symbol, the limit generally depends upon core size balanced against the number of unique symbols in a program. 

The most obvious technique for reducing core requirements during an Extended Symbol assembly is to reduce the 
number of unique symbols in the program. This can be accomplished by using several LOCAL regions in the program 
and using the same LOCAL symbols for each region, as shown in the following example: 





LOCAL 


$10, $20, $30 


AROUTINE 


RES 





$10 


RES 





$20 


RES 





$30 


RES 







LOCAL 


$10, $20 


BROUTINE 


RES 





$10 


RES 





$20 


RES 






END 



The above technique is practical in most programs since programs are often divided into many separate routines; the 
routine name being global to the whole program, but many symbols within the routine are referenced only by that 
routine. 

Note that main-level LOCAL symbols do require RAD or disk space during an assembly. The requirements are three 
words per symbol per LOCAL region. The above example would thus require 15 words of bulk storage. Since a 
blocking buffer is required for the LOCAL (X3) file, this technique must be used consistently over moderate-to- 
large programs before the savings in core storage becomes effective. 
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11. HOW TO USE HARDWARE INTERRUPTS 



This chapter forms a natural division in the organization of the User's Guide. All previous topics have dealt either 
with purely background applications or with those services and procedures used in common by both foreground and 
background. The descriptions and suggestions for using the hardware interrupt system given below mark the entry 
into the real-time world of RBM, and it is recommended that some attention be given to this material before going 
on to succeeding chapters. By studying the capabilities and implications of the hardware interrupt system, you will 
be better able to call on these resources in a way best suited to your own foreground programming requirements. 

In particular, all foreground users should at least be cognizant of the internal interrupt structure and purposes of 
the RBM Tasks that comprise the Monitor, since RBM is itself a real-time program that must respond to time-critical 
events such as I/O interrupts and operator interrupts. The interrupt levels of the RBM Tasks and their interrelation- 
ship with user tasks and programs are described briefly at the end of this chapter as an example of one way to use 
hardware interrupts. (A description of the Tasks' functions is given in the Real-Time Programming chapter of the 
RBM Reference Manual.) 

Note that some foreground programs can utilize interrupt levels without being real-time programs, and one sugges- 
tion for such use is given later in this chapter. 

PURPOSE OF HARDWARE INTERRUPTS 

The Sigma hardware architecture includes a powerful hardware priority interrupt system. This consists of a multi- 
level interrupt structure composed of both external and internal levels arranged in an expandable, flexible, and 
partially pre-selected order. RBM has been specifically designed to use this hardware priority interrupt structure 
to the fullest extent possible, and this particular structure's purpose is to efficiently allocate the CPU. The impli- 
cations of this structure are described in detail to suggest ways that you can use Sigma interrupts. For if you do not 
take advantage of these features when designing a real-time system, the full power of the hardware approach is lost. 
To get the maximum utilization out of a Sigma 2/3, your real-time system design should be based on a clear under- 
standing of the power and flexibility of the hardware interrupt system. 

The detailed implications of Sigma interrupts are as follows: 

• Fast real-time response: On the occurrence of some predetermined external or internal event, the 
Sigma 2/3 can stop its current operation and switch to an entirely different operation within a few instruc- 
tions. This permits real-time programs to operate in a time-critical manner. 

• Priority response: Since each hardware level has an implied priority (by its position in the interrupt chain) 
and since a level only interrupts the CPU if it is the highest active level, the CPU is guaranteed to al- 
ways be working on the most important (highest priority) operation that needs attention in the system. 

• Low overhead; No time is spent by the CPU in posting to software queues, periodically scanning these 
queues, and checking to see if something new has arrived on the ready queue that is higher priority than 
the current operation; instead this is all done automatically by the hardware priority interrupt system. In 
fact, this system can be viewed as a separate "processor" that executes in parallel with the CPU, main- 
taining a "queue" in the interrupt hardware and operating in a microprogrammed fashion to do the sched- 
uling for the Sigma 2/3 CPU. Thus, the Sigma 2/3 CPU can be involved with solving user problems 
instead of trying to decide what to do next. 

• Noninterference: When events of a lower priority than the currently executing program become ready, this 
fact is noted by the hardware interrupt system but the CPU Is not diverted away from Its currently more 
important operation (even for a microsecond) to record the fact and make a decision relative to the priority 
of these two tasks; this decision is accomplished automatically In the interrupt hardware. 

• Asynchronous operation: The hardware interrupt system is truly asynchronous; that is. It executes a task at 

a specific interrupt level only when that level goes active as the result of some specific event. If the times 
of such an event are variable and random, this asynchronous but immediate response Is highly important. 
(Asynchronous operation is considered in detail later in this chapter. ) 

• Anonymous operation: The design of tasks need not be concerned with what other tasks may be operating 
when an interrupt occurs, or what context the interrupted task was using upon entry. Each task saves (In 
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its own area) the registers and other temporary working storage that it will modify, does its own function, 
and then restores these registers independently of what the other task was. Thus, this is a strictly LIFO 
(last-in, first-out) method of scheduling that minimizes debugging and design problems. Another way of 
defining anonymous operation is that an interrupted task is never aware that it was interrupted, except 
where timing considerations (such as real-time clock pulses) are a factor, 

• Flexibility: From one to 100 interrupt levels can be used and they can be arranged in various priority 
levels; some above and some below the I/O level and other RBM levels. By selecting the number of inter- 
rupts, the groups of interrupts, the priority of these interrupts, and the source of activation pulse for each 
level, each installation can fit its own unique demands. 

SUMMARY OF HARDWARE INTERRUPT FEATURES 

A complete description of the features of the hardware interrupts can be found in the Sigma 2 or 3 Computer Refer- 
ence Manuals. However, the key points as related to your program design can be summarized in this chapter. 

The interrupt "environment" (CONNECT, ARM, ENABLE, INHIBIT) is controlled either directly through special RD 
or WD instructions coded into your program, or indirectly through RBM Monitor service routines accessed by calls, 
key-ins, or control commands. The hardware interrupts for Sigma 2/3 computers possesses the following 
characteristics: 

No level may advance to an active state while a higher level is active. 

Under program control, individual levels (or "groups") may be set to ignore incoming signals (DISARMED) 
or to postpone reaction to these signals until some later time (DISABLED or group INHIBITED). 

The initial condition of all interrupt levels (except the override group, when the options exist) is DIS- 
ARMED and DISABLED. 

Interrupt levels may be TRIGGERED either by program control or by external signals. 

All levels (except the override group) may be inhibited by a single instruction; the inhibit may also be 
removed by a single instruction. 

The internal and external interrupts can be inhibited either separately or at the same time. 

The previous state of interrupt inhibits can be saved, and new inhibit conditions set or reset in a single 
instruction. 

The previous interrupt inhibit state is saved (in the old PSD) on a task entry sequence, and the first instruc- 
tion of the task is always executed before another interrupt con take place; thus, this first instruction can 
inhibit all further interrupts if desired. 

No level may advance from the waiting state to the active state unless it is ENABLED and not inhibited. 

The hardware priority sequence may be arranged in virtually any priority order, either above or below the 
I/O group. The override group is always high. 

An interrupt level should not be DISARMED while it is active because the results are unpredictable. Since 
the hardware priority search during the EXIT sequence is based on certain mutually exclusive states of the 
interrupt flip-flops, DISARMING causes a level to be ignored even though it is active. 

Only one-level of signal is remembered by interrupts. That is, if a level is already waiting to go active, 
another TRIGGER will have no additional effect on it; and if a level is already active, another TRIGGER 
is ignored. 

Some of the implications of these characteristics are as follows: 

• Real-time programs can be debugged by using software triggering for certain levels before the real-time 
hardware is connected. 
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• Real-time programs can work in groups by using internal WD (Write Direct) instructions to TRIGGER 
various levels; thus, a high priority level may be connected to external signals and collect data at the 
high priority, and then TRIGGER a lower priority to process the data at its leisure. 

• Under program control you can select which interrupt levels to initially ARM and ENABLE, and can reject 
or postpone future signals based on program logic or program computations. 

• Real-time programs that have to inhibit interrupts anywhere (except as the first instruction on task entry) 
should do so by a save-and-inhibit sequence (a special RD instruction). Later, they should never "remove" 
interrupt inhibits but should always "restore" them to their previous state; either by executing an EXIT se- 
quence (and using the old PSD), or by a "restore" sequence that uses the information from the save-and- 
inhibit sequence. This is because some tasks may inhibit externals and not internals, or vice-versa. 

• If on active task wishes to have all future signals to its own level ignored, it should DISABLE this level 
and EXIT rather than DISARM it and then EXIT. Some future, lower-priority task can DISARM the 
disabled level if this is really necessary. One should not DISARM an active level. One should also not 
ARM an active level since this interferes with the current state. 

INTERRUPT TASK SCHEDULING 

The possibilities for real-time task scheduling based on these hardware interrupts are very brood, subject only to the 
LIFO requirement. The several suggestions given below are meant to be general guidelines only. 

A particular interrupt level can be used to uniquely identify an event that requires processing. At the same time, 
it establishes the priority of this processing relative to other levels. Or, an interrupt level (such as the I/O level) 
may only identify a class of possible events, and further information may be required to identify the specific event. 

When a series of tasks, each of which is connected to separate interrupt levels, all use the same database (tables 
or files), the other tasks in the group can be DISABLED while any one of them is modifying critical portions of the 
database, and it still permits higher priority interrupts in another group to become active if necessary. A general 
inhibit instead of a DISABLE would not permit this. Also, any signals to the DISABLED tasks will be "remembered" 
for later processing, which would not occur if a DISARM were used. 

A task connected to a level higher than the I/O level can be activated from some critical real-time event (such as 
an over-temperature condition in a process plant), and this task Is guaranteed 100 |js response to any signals, as- 
suming this is the highest real-time user level, since RBM never inhibits interrupts for longer than 100 us. 

A user task at a high priority level may sample some data input devices periodically and then TRIGGER other, lower- 
priority levels associated with some particular condition that requires further processing, and such processing can be 
performed at a lower level that is commensurate with the importance of the particular condition. 

RBM itself uses some interrupt levels for its own processing as identified in the RBM Reference Manual. But gen- 
erally speaking, RBM does not interfere with the real-time interrupt levels and user programs are free to make their 
own scheduling rules. 

It is by no means necessary to limit the use of interrupt levels to real-time operations. A tape-to-printer routine 
in the foreground can be connected to an interrupt level and can use the AIO Receiver and no-wait I/O operations 
to schedule and synchronize itself in order to buffer output to a printer, and so permit other (lower priority) tasks 
(including the background) to execute while I/O is in progress for this task. 



SOFTWARE SCHEDULING OF SUBTASKS 

We stated earlier by implication that attempts to schedule CPU allocation through user software, rather than taking 
full advantage of the hardware features, would result in degradation of the system. This is true at the primary task 
level but software scheduling within a task can be useful. While the primary (task) scheduling in RBM is strictly 
off the hardware priority interrupt system, it is possible for a task at a particular hardware interrupt level to organ- 
ize itself into a series of subtasks . 

Suppose that in your installation a very large number of distinct real-time events are possible. And suppose that 
many of them are processed in little groups, each related in some way to an external event. It is not necessary to 
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have a separate task with a separate interrupt level for each of them. There is a concept of secondary scheduling 
that can be controlled by user software, at your discretion, through any of a number of schemes. 

When the primary task is activated by its hardware interrupt, it might identify a subtask (or subfunction or subevent) 
to be performed by means of status information read in from the external equipment. Communications equipment and 
analog or digital converters very often operate this way. Or, a fixed number of subtasks under the primary task 
might be processed sequentially if their execution sequence is always fixed and always known. Or again, the pri- 
ority of each subtask might correspond to a bit in a software status word and the primary task might search the status 
word from left to right, looking for the highest priority subtask to process. These bits might be set by the primary 
task or by other subtasks, based on conditions during the processing of these subtasks. 

Many other methods are also possible. A primary task could be thought of as special foreground executive, with 
the job of scheduling the activity of a set of related subtasks. As a special RBM service, there are 32 dedicated 
locations in low core (mail boxes) available to all real-time programs to aid in this intratask communication. 

The rules for determining which events should be processed as primary tasks and which as subtasks are very simple: 

1. At least a portion of all primary tasks must be resident to answer a hardware priority interrupt. Subtasks 
can be resident or can be nonresident overlay segments; if overlaid, the overlays are controlled from the 
primary task by calls to RBM service routines. 

2. All subtasks must operate to completion (in regard to other subtasks at the same level) or until they explic- 
itly release control back to their primary task executive before another subtask at this same level can be 
scheduled. Thus, the types of events that can operate as subtasks are restricted in regard to other subtasks 
at this level, since this is basically synchronous operation. But they are not restricted relative to other 
primary tasks. Primary tasks at separate interrupt levels can interrupt each other immediately when an 
event occurs that needs attention. Thus, primary tasks are basically asynchronous and are much more 
responsive than subtasks. 

3. Control of subtasks is centralized at their primary task and is exercised through software . Primary tasks 
are controlled with decentralized hardware scheduling. 

RBM ORGANIZATION 

To better illustrate the idea of programs, tasks, and subtasks, the detailed structure of RBM should be examined, 
since RBM Is itself a real-time program with several tasks and subtasks. RBM uses up to nine of the fixed hardware 
priority levels on a Sigma 2/3 and one assignable external interrupt level that is controlled by software triggering 
from other tasks or from Monitor service routines. This priority interrupt structure is illustrated in Figure 50. The 
RBM Control Task level is designed primarily for operator control and for control of the background, and must not 
interfere with the foreground. Thus, it must always be assigned to an interrupt level be I ow all the foreground pri- 
ority levels. The resident part of this level causes the various RBM subtasks to be loaded from the RAD as needed. 

The other RBM tasks perform a minimum of analysis at their level, set status bits in the RBM Control Task control 
word, trigger the RBM Control Task level, and then exit. For example, when the operator activates the Control 
Panel interrupt, which is just below the l/O interrupt and above most of the real-time tasks, this RBM Control Panel 
Task sets a bit in the RBM Control Task status word to signify that the operator key-in subtask is needed, and then 
triggers the RBM Control Task. Thus, operator key-ins do not interfere with foreground operation, since these key- 
ins are designed to control batch background processing. Similarly, if the background tries to execute a privileged 
instruction or tries to branch to protected core, the Memory Protect task is activated; this task sets the Abort subtask 
flag, triggers the RBM Control Task, and then exits. From the address in the program status doubleword, the RBM 
Abort subtask can tell the exact location causing the protection violation. This information is printed in the abort 
message to aid in debugging background programs. The printing of messages and the deactivation of the background 
does not interfere with foreground operation. Thus, the entire set of RBM tasks works as an asynchronous whole to 
control the operation of the system. 

Discussion on the RBM handling of input/output to achieve multi-task operation is in order at this point. Remember 
this fundamental rule: 

• All input/output is initiated and checked for completion at the priority level of the requesting task. 
Further, all input/output uses interrupt control to coordinate I/O activity. 
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Figure 50. RBM Hardware Priority Interrupt Levels 



To prevent the problem of I/O hang-up on shared devices like the RAD, the I/O Interrupt Task in RBM saves end- 
action status information in a task context area called a Device File Table that is unique to each task. For example, 
if the background initiates an operation on the RAD and then is interrupted by the foreground before the operation 
is complete, the I/O Interrupt Task saves the device status at channel end in the specified background Device File 
Table and frees this device for further use. The foreground may then use this device. Later, when control returns 
to the background and when the data is needed, a check is made to determine if the operation was completed suc- 
cessfully. If any retries are necessary, they are performed here. Otherwise, the operation is complete. Standard 
error recovery is provided for all devices, but user programs can elect to treat errors in any manner they choose. 

A very important service that is in keeping with the philosophy of asynchronous operation is the AIO Receiver. This 
permits a foreground task to initiate I/O with a no wait option. When the Monitor has then successfully initiated 
the I/O operation, it returns control to the foreground task; the foreground task can then set a flag for itself that 
I/O is pending and exit to a lower priority task (or to the background). Later, when this level becomes active, 
processing will continue for that task. This feature can be used in the foreground to permit more efficient use of 
the computer. Thus, users have a choice about releasing control during I/O operations. This is an efficient way 
to buffer or queue I/O operations for foreground tasks. (A foreground program could have one task to do nothing 
but queue and buffer for other tasks, for example. ) 
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12. HOW TO CREATE A TASK CONTROL BLOCK 



A Task Control Block (TCB) is a convenient means for storing and organizing the information required to allow 
various foreground tasks to operate and interrupt each other in an orderly manner. The Monitor assumes that a 
TCB is the first loadable item within a foreground program. The TCB is used by the Monitor service routines 
M:SAVE, MrEXIT, MrLOAD, M:OPEN, M:CLOSE, and also when a C: (connect) control command or C key-in is 
read. (See the next chapter, "How To Connect Tasks To Interrupts" for more details about TCB and C: interface. ) 

You have two alternatives in the creation of a Task Control Block for foreground use: code your own TCB (if pro- 
gramming in Extended Symbol), or allow the Overlay Loader to create it. If you wish to code your own TCBs, refer 
to Chapter 6 of the RBM/RT, BP Reference Manual, 90 10 37 for detailed information on TCB composition. The in- 
formation given below deals entirely with Loader-built TCBs. 

If the Loader builds the TCB, it does so completely; that is, no initialization of the TCB by the user is allowed. 

A foreground root may contain one or more tasks, with each task connected to its own interrupt. This is accom- 
plished through multiple Overlay Loader !$TCB commands within the root loading sequence. The first !$TCB com- 
mand jmjst precede the !$ROOT command and is called the "initial" TCB. The only difference between it and 
subsequent !$TCB commands is that a "temp" parameter on the initial !$TCB command is ignored; instead, the value 
of the "temp" parameter from the !$ROOT command is used. 

The other two parameters on the initial !$TCB command, W] and W2, are placed by the Loader in the next two loca- 
tions of the TCB. For simplicity, these words are usually written as hexadecimal numbers (e. g. , preceded by a +), 
although if desired, they could be written in decimal. Groups of bits within these two words are used as indicators 
and interrupt locations. See the "Task Control Block" table in Chapter 6 of the RBM/RT, BP Reference Manual, 
90 10 37 for more detailed TCB construction. 

The first parameter, w,, is constructed as follows: 

Bits 0-3 contain the A register bit number for a Write Direct instruction. This is a number from through F 
(hexadecimal) associated with each individual interrupt within its group. Refer to Table 1 in Chapter 2 of the 
Sigma 3 Computer Reference Manual, 90 15 92. The list of numbers below the heading "Write Direct Register 
Bit (3)" of this table is the A register bit number referred to above. 

Bit 4 is a flag indicating whether the Monitor should set core locations 1 through 7 when M:SAVE or F:SAVE is 
called. If any Monitor service routines are called within the task, bit 4 should be zero indicating that the 
Monitor is to set these core locations. 

Bit 5 is not used but should be zero. Bit 6 indicates whether the interrupt should be triggered when the task is 
loaded ("1" means trigger, and "0" means not to trigger). 

Bits 7-15 contain the core location (in hexadecimal) of the particular interrupt to be associated with this task. 
Refer again to Table 1 in Chapter 2 of the Sigma 3 Computer Reference Manual 90 15 92. The leftmost column 
in this table gives the location for each interrupt. 

Assuming that w-i was written as +C30C, the indicators would mean that the interrupt wired to location X'lOC (268) 
is associated with this task, the Monitor is to set core locations 1-7 (the usual case), and interrupt X'lOC is to be 
triggered when its task is loaded into core. Remember that the Overlay Loader does not load programs into core; 
this is the function of the M:LOAD Monitor service routine. 

The second parameter, w«, is constructed as follows: 

Bits 0, 1,2,4 and 8-11 are always zero, and bit 3 is always 1. Bits 5,6 and 7 contain an "operation code" that 
is used with the Write Direct instruction. The "Interrupt System Control" section in Chapter 2 of the Sigma 3 
Computer Reference Manual, 90 15 92, describes the action taken with each of these codes. Bits 12-15 of W2 
contain the Group Number of this interrupt. These numbers are listed in the rightmost column in Table 1, in 
Chapter 2 of the Sigma 3 Computer Reference Manual. 

Assuming W2 contained +1200 in conjunction with a W] containing C30C as described previously, this would cause 
interrupt X'lOC to be armed and enabled when the task is brought into core. This means that when the program 
task is loaded into core, interrupt X'lOC would be armed and enabled (the "2" in 2 S+1200) and then triggered 
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(since bit 6 in 1 is a 1), causing the computer to set its P register to the address contained in location X'lOC. 
This address would hove been stored in this location by M:LOAD, using information placed in the task's TCB by the 
Overlay Loader. 

The flexibility of the "operation code" technique for interrupt control allows the user a wide variety of interrupt 
handling methods. For instance, if this example used a code of 3 (that is, if W2 were +1300), the interrupt would 
have been armed and disabled on loading. The Monitor would have tried to trigger it, but no action would have 
occurred. However, since an'interrupt that is armed and disabled "remembers" a trigger, a different task could 
enable this level, which in turn, would cause interrupt X'lOC to go "active" (transferring control to its task) as 
soon as it became the highest priority active interrupt. 

You may define multiple tasks within a single root by having additional !$TCB commands subsequent to the initial 
l$TCB command. Each must be followed by one or more !$LD commands to load the ROMs for that task. A l$TCB 
command may also be followed by a !$BLOCK command to specify any opibs that may require blocking buffers in 
that task. 

The "temp" parameter on !$TCB commands subsequent to the initial one is used to reserve temporary space in the 
same way as on the !$ROOT card. If the "temp" is absent, a default value of 80 (X'50') is supplied by the Loader. 

Since there is a heavy interface between the !$TCB commands and C: control commands or key-ins, it is recom- 
mended that you now turn to the next chapter, "How To Connect Tasks To Interrupts". 
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13. HOW TO CONNECT TASKS TO INTERRUPTS 

The function of linking a foreground task to its interrupt, and optionally controlling the state of the interrupt is 
performed through the Monitor !C: control command or the C: operator key-in. The !C: control command and 
C: operator key-in function in precisely the same way and have identical parameters. For brevity, they will be 
termed "Connect" commands in the rest of this chapter. A frequent use of the Connect commands is to check out 
real-time systems that use externally triggered Interrupts. Once the foreground is initialized, operation of the 
various tasks may be checked without the necessity of actually applying signals to the interrupt lines. 

The first and mandatory parameter for a Connect command is the first core location of the task's TCB. The second 
and optional parameter is an "operation" code. This is a number from 0-7, and if present, is used by the Monitor 
in place of the code contained in bits 5, 6, and 7 or word 2 of the TCB; that is, w^ on the !$TCB command. How- 
ever, the data in the TCB is not changed. 

For instance, assuming a foreground task had been loaded with a !$TCB command where w„ was +1100, it would be 
brought into core with it's interrupt disarmed. A C: key-in with a code of 2 could then be used to ARM and ENABLE 
the interrupt. A second C: key-in (for the same TCB) with a code of 7 would then TRIGGER the interrupt, and if 
no higher-priority interrupt were ACTIVE, the task would receive control. 

Note that if you request the Overlay Loader to build a TCB, but have supplied a transfer address (that is, a label 
in the argument field of your END statement), M:LOAD will honor this as an initialization entry point and this 
address will also be used for interrupt entry. If this is not appropriate, you must alter it in your code. If the 
Loader builds the TCB but no transfer address is supplied, the interrupt entry will be the first word of the program. 
The Loader will output a "OLERR TA" message and set an error level of 1; however, this is only a warning message 
and does not affect program execution. 



The location of the task's TCB is the location immediately following the keyword "ORG" on a load map. See the 
load map example in Chapter 6, "How To Build an Overlay Program". 
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14. HOW TO ATTAIN REENTRANCY IN ASSEMBLY LANGUAGE SUBROUTINES 



Reentrancy in a subroutine permits the subroutine to be interrupted during its execution for one task by a higher 
priority task, entered and executed by the higher priority task, and later reentered and continued for the original 
task with all previous environment saved. The advantage of reentrancy, of course, is the savings in memory space 
achieved by the sharing of procedural code. 

Reentrancy is made possible through the use of two special hardware registers: the base register and the link register. 

The base register (B) is used by reentrant routines to point to a temporary scratch area (called the "temp stack"), 
that is allocated by the Loader, and is unique to each task. The base register contains an absolute core address 
that is the start address of the temp stack. Note that the Sigma 2/3 instruction set permits use of both a base re- 
gister and an index register (with or without indirect addressing) which is a powerful technique for manipulating 
data and address values. 

The link register (L) is used in reentrancy to save the return address in all subroutine calls. Since no subroutine 
area can be modified, a method for subroutine calling that uses a branch-and-store instruction counter will not 
work, because it would store the return address in the subroutine area. However, with the link register as a sep- 
arate register for the return address, linking is quite easy. 

With the exception of the B register, all of the hardware registers can be used as a temporary scratch area in a man- 
ner similar to temp stack usage. 

There are two inter-dependent software parts that are responsible for providing reentrancy: the task and the reen- 
trant subroutine. If the proper conditions are not met in both items, no reentrancy is possible. That is, the task is 
not itself reentrant, but if it calls a reentrant subroutine and the subroutine requires more working storage than can 
be provided by the general registers, then the calling task must provide a temporary storage area for the reentrant 
subroutine. The reentrant subroutine will use this area as required. 

When a task's interrupt occurs, the pointer to the temp stack of the interrupted task is switched by the interrupting 
task via the M:SAVE Monitor service routine. This pointer (K:DYN) is set in the task's TCB to identify the temp- 
orary work area for the reentrant subroutine. In order for the subroutine to get the B-register set to the unused part 
of the stack, it should call M:PUSH upon entry. To release this space before the subroutine exits, it should call 
MrPOP, This temporary space is illustrated in Figure 51. 

The address of the temp stack is in word 3 of the Task Control Block. This address can also be found in location 6 
(K:BASE). The best method for using the stack for temporary storage of up to "n" words is to use the M:RES and 
M:POP Monitor service routines, where the calling sequence 

RCPYI P, T 

B *$+3 

DATA n (number of cells) 

DATA 

ADRL M:RES 

would save the previous value of B in the temp stack and set B to the FWA of the temporary scratch area (within the 
temp stack) being allocated, and the sequence 



LDA 


=RETURN 


STA 


2,,1 


B 


M:POP 



would set up the return to TEMP+2, after releasing the current temp storage stack and restoring the previous 
value of B, 
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Figure 51. Reentrant Subroutine Calling Example 



The size of the required temp stack is determined by the maximum nesting of subroutine calls. For example, assume 
the following events: 



Task C calls Subroutine 2, v/hich requires 15 v/ords of temporary space. 



Subroutine 2 calls Subroutine 3, which requires 8 words of temporary space. 



Task C must therefore provide a temporary stack with a minimum of 23 words. 



Let's further assume that Task C has a total of 50 words of temp stack. The temp stack would then appear as illus- 
trated in Figure 52 when Subroutine 3 was executing. 

During the execution of Subroutine 3, the base register does not point to the beginning of the temp stack, but in- 
stead, points to the beginning of space required for Subroutine 3. 

If Task C had called Subroutine 3 directly instead of indirectly from Subroutine 2, the space required for Subrou- 
tine 3 would have been at the top of the stack. 
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Figure 52. Temp Stack Usage Example 



In summary, then: 

• Tasks that call reentrant subroutines must reserve adequate temp stack space and get this space pointed to 
from the TCB, via a call to M:SAVE. 

• Subroutines designed to be reentrant must call M:PUSH (or M:RES) to set the B-register and reserve space, 
must use base addressing to reference this space, and must call M:POP to release this space. 

Procedures for assembly language calls to reentrant FORTRAN Library routines are discussed in detail in Chapter 8. 
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15. HOW TO WRITE AN ASSEMBLY LANGUAGE INTERRUPT HANDLER 



The sample assembly language program example illustrated in Figure 53 and 54 will output the message 



KEY-IN THE DATE AND TIME BEFORE PROCESSING ANY JOBS 



on the OC device when any of the following conditions are encountered: 

• Each time the system is booted in from a RAD or tape, 

• Whenever a trigger is initiated by either a C: control command or C: operator key-in. 

• Whenever a Iname processor command is encountered, preceded by an FG operator key-in. 

Figure 53 shows the source listing and required control commands and Figure 54 shows the assembled program. The 
message 



OLERR TA 



that appears following lOLOAD in Figure 53 is expected and is to be ignored. 

At execution the program is loaded into memory and is armed/disarmed, enabled/disabled, and/or triggered in ac- 
cordance with the specification in the Task Control Block (TCB). The TCB in this program arms and enables the 
interrupt and triggers when the program is loaded in. 

When the message 



KEY-IN THE DATE AND TIME BEFORE PROCESSING ANY JOBS 
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Figure 53. Interrupt Handler Source Listing 
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Figure 53. Interrupt Handler Source Listing (cont. ) 
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NEW LINE / NEW LINE 


2» 


0011 

oou 

0019 
001* 
0019 
001« 
0017 
0019 
0019 
OOIA 

ooia 


DSC5 
E860 
C905 
40E:3 
C8C5 
40C4 
C1E3 
C540 
C1D5 
C**0 
E3C9 


A 
A 
A 
A 
A 
A 
A 
A 
A 
A 
A 




TEXT 


'KEY-IN THE OATE 


AND TIME BEF8RE PRBCESSINQ ANY jBBS 1 



Figure 54. Interrupt Handler Assembly Listing 
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DUO 



0*/0l/7X PAGE 



OOIC 
OOiB 
OOU 
OOIF 
0020 
0021 
002^ 
0028 
002* 
002S 
002«i 
0027 
0028 
002? 
002A 
0028 

OOaC 



'»0C2 
C5C6 
D609 
C5*0 
0709 
D6C3 
C5E2 
E2C9 
D5C7 
40CI 
D5E8 
*00l 
D6C2 
£2*0 
1515 

E6C5 
00C9 
OOCE 
00^0 



XtCBDE DATA 

MJWRITE EQU 

MJABSRT EQU 

m:exit EQU 



2(k 0028 1515 A DATA 

H7 

29 

28 

90 

31 

38 

3i END 

N9 WARNINU LINES 
N8 EKKeH UINE5 

EKneR severity; 



SIQMA 2/3 CRBSS REFERENCt LISTING 



X<1515' 



'WE" 
X»C9' 
X'Ce» 
XfOo' 



NpW LINE / NEW LINE 
ABORT CODE WRITE ERRBR 

Transfer address FeR rbm write 
Transfer address for rbh abort 

TRANSFER address FOR RBM EXIT 



u 




A 


9 


c 


18 


ARG 




c 


17 


ARQJADDR 


5 


u 




L 


6 


E 


30 


fllASIBRT 


12 


E 


31 


MIEXIT 


I* 


E 


29 


rn WRITE 


7 


C 


23 


MESSAGE 


20 


u 




P 


6 


C 


5 


TYPS 


1 


C 


13 


wRITEtSK 


3 


c 


28 


XtCODE 


10 


u 




« 


17 


END CROSS REFERENCE I 




tr-ooo. 


7i 






Pause ^tr-iN fg/s 




ASSIGN 


qV'GREET|NG#UP 




tJLBAD 


0#F 






•MS 








• TCB 


♦i3U**1205 




«Hi59T 


;oo/ 


«3000#Ge/l 




•tvjD 
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13 



11 



13 



BLeRR ta 



<JeB GRE&TINQ |B 

0*/0l/7X 0002 

t'AUSE KfY.IN SY,S TB UN.KR8TECT THE RAD 

RAOeDIT 

*ADD UP#eREETINe*3»iR,R#F 

• END 

tT«O0Otl8 
ASSIGN S2*S24RBM«SD 
XSYHBOU UB/GOiCR/NS/DW/BB 



Figure 54. Interrupt Handler Assembly Listing (cont, ) 
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Fe BR6«3000 HUeC.30AB CBAS-9KEE 


CSU-0000 


UMEM,2F42 SECT, 


lOooa 


ROOT 0^6*3064 


LWA»30*C 


UEN«0049 TRAaNSNE 
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Figure 54. Interrupt Handler Assembly Listing (cont. ) 
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16. HOW TO WRITE AND EXECUTE A REAL-TIME PROGRAM 



The source listings in Figures 55 and 56 illustrate the interface between two real-time task examples. The first task 
calls for a checkpoint of the background, specifies the Checkpoint Complete Receiver (via the M:CKREST Monitor 
service routine and is used similarly to the AIO Receiver), and then exits itself. The task is reentered at channel 
end. The Checkpoint Complete Receiver then triggers a second, higher priority task to restart the background. 

The deck structure given in Figure 57 would load and cause execution of the two real-time tasks illustrated in 
Figures 55 and 56. 

When both tasks have successfully executed, the message 



CKPOINT SPECIFIES AIO RECEIVER 
!!BKG RESTART 



will be output on the operator's console. 
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f, 
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A 




B 
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7 
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A 
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R 


OOOV 


6FFF 
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B 
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U 
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COOO 


A 


AA 
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IR 
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DATA 
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If, 
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MD 
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Figure 55. Real-Time Task Example, Checkpoint Call and Exit (Task 1) 



1 




0001 


A 


P 


EQU 


1 




? 

3 


0000 
0001 
0002 


0002 

C81B 
7bAl 

4C1A 


A 

A 
A 
A 


L 
START 


EQU 
REF 
UDX 
RCPYI 
B 


2 

m:exiTiMjckrest#mjwrite 

«BB WRITE 9U'T riESSAiiE 

p/l in ebcidic 
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****«««««**»««««««««* 
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Figure 56. Real-Time Task Example, Restart Background (Task 2) 
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IR 








*««»*«*«««««««*«#«»«* 


1«J 


0008 


3005 


A 


BB 


DATA 


X'3005' 


20 


0009 


D6C3 


A 




DATA 


»ec' 


21 


OOOA 


oooc 


R 




ADRL 


BUFFER 


2? 


OOOB 


OOIC 


A 




DATA 


28 


23 


OOOC 
OOOD 
OOOE 
OOOF 
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OOll 
0012 
0013 

oou 

0015 
0016 
0017 
0018 
0019 
OOlA 


40C3 
D2D7 

E340 
E2D7 
C5C3 
C9C6 
C9C5 
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C1C9 
D640 
D9C5 
C3C5 
C9E5 
C5D9 
4040 
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Figure 56. Real-Time Task Example, Restart Background (Task 2) (cent. 






lEOD 



XSYMBOL deck (Task 2) 




IXSYMBOL LO, GO 



IJOBC 



lEOD 



I'^ADD UP, AIO, 2, R, R, F 



i'^ADD UP,CKPTAIO,2,R,R,F 



IRADEDIT 



! PAUSE KEY-IN SY, S 



I PAUSE KEY-IN FG,S 



lATTEND 



!JOB 



Figure 57 . Deck Example For Loading and Executing Real-Time Tasks 
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!XEQ 



!EOD 



!$MS 

!$ROOT ,+2600, GO, 1 



!$TCB +1311, +1205 



lOLOAD 0,F 



lASSIGN OV=AIO,UP 



/ 



!EOD 



XSYMBOLdeck (Task 1) 




IXSYMBOL LO, GO 



!JOBC 



!XEQ 



!EOD 



!$MS 



!$ROOT ,+2700, GO, 1 



!$TCB 40110, +1205 



lOLOAD 0, F 



lASSIGN OV=CKPTAIO,UP 



y 



where the flagged control commands hove the relevance and meaning given below: 

1. Permits loading into the foreground, 

2. Permits modifications to the RAD area. 

3. Creates two files: AIO and CKPTAIO. The files are to be two records (sectors) long, 
random access, resident foreground, and have RBM write protection, 

4. Core image output by the Overlay Loader goes directly on file CKPTAIO, 

5. Task is connected to interrupt +01 10 (or 272]q in decimal) in external group 5. The interrupt is 
armed and enabled but is not to be triggered when loaded into memory for execution, 

6. Starting address is +2700 (temp stack FWA), 

7. Task is connected to interrupt +0111 (273]0 '" decimal) in external group 5. The interrupt is 
armed and enabled, and is to be triggered when loaded into memory for execution. 



Figure 57, Deck Example for Loading and Executing Real-Time Tasks (cent.) 
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When designing and coding your own real-time programs, there is a cardinal rule to be remembered. It was touched 
upon in previous chapters but is so important and fundementcl to RBM design that it deserves added emphasis: 

• Each and every foreground task must be connected to a hardware priority interrupt and therefore will exe- 
cute if and only if its interrupt level is ACTIVE. In particular, a foreground task must not continue exe- 
cution if the interrupt level is removed from ACTIVE status for any reason. 

The single exception to this rule is during the initialization phase of a foreground program, which is run at the 
RBM Control Task level. (Exit from initialization must return to the RBM Control Task. ) It is assumed that initiali- 
zation activity is of short duration. 

The priority level of user foreground tasks must be above the priority level of the RBM Control Task and below the 
I/O priority level if any I/O is to be performed by the user task. 
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17. HOW TO CREATE A FORTRAN REAL-TIME SYSTEM 



Using ANS FORTRAN IV, you have the ability to construct a Sigma 2/3 real-time system that may be entirely 
written in FORTRAN if desired. 

REENTRANCY 

To effectively use a FORTRAN program in a real-time environment, it is necessary to structure the subprograms so 
that they are reentrant. The Main program and TASK Main programs are, as noted elsewhere, not reentrant; how- 
ever, any subroutine that may be reached from the Main program and a TASK Main program or two TASK Main 
programs must be reentrant if the system is to function properly. As indicated in Chapters 13 and 15, Sigma 2/3 
programs achieve reentrancy through separation of program and data and the use of a dynamic temp stack allocated 
by the Overly Loader. 

The standard object code output by the ANS FORTRAN compiler is designed so that it may be transformed into reen- 
trant subprograms. Such a transformation is achieved through the following requirements: 

• The subprogram must use M: RES, M:MPUSH, M:PUSHC, or M: PUSH K for its storage allocation. 

• The temp stack must be allocated at the very end of the subprogram. 

• The temp stack must not contain any preset data. 

• The program area must not be modified during execution. 

When made reentrant, a subprogram is set so that it uses the dynamic temp (see the "Public Library FORTRAN Rou- 
tines" subsection later in this chapter). 

TASKS 

The key to the generation of a real-time FORTRAN system is the TASK Main program, which is a Main program 
having a TASK statement as its first statement. The TASK statement provides a means of naming (other than with 
F:MAIN) a Main program so that it may be used by the CONNECT subroutine. Thus, TASK Main programs are the 
interrupt entry points used in constructing a real-time FORTRAN system having more than one entry point. Note 
that tasks themselves are not reentrant; however, they provide temporary space to any reentrant subprograms and to 
Monitor service routines. 

BASIC STRUCTURE 

An example of a possible real-time FORTRAN system is shown in the schematic given in Figure 58. In the example, 
the Main program provides the initialization for the rest of the real-time system. Initial entry would be to the Main 
program, which would then connect the tasks ALPHA and BETA. 



Interrupt A 
(optional) 

Interrupt B 
Interrupt C 










S 
U 
B 

R 

O 

U 

T 

I 

N 

E 

S 




Main Program 
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Figure 58. Sample Real-Time FORTRAN System Schematic 
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If the main program Is to be connected to an interrupt, it will be necessary to have the Main program alter a preset 
variable so as to flag the fact that the later entries are not to do initialization. 

Figure 59 shows the deck setup that might be used to construct the schematic sample in Figure 58. The first !$TCB 
card instructs the Overlay Loader to initiate the root segment through the w„ w» specification. 

The !$ROOT card tells the Loader the size of the Main program's temp stack (t^) and also where to find the Main 
program and the subroutines BI. 

The second !$TCB card sets the Loader to expect a TASK Main program (t2) which will be task ALPHA, and also 
causes the Loader to allocate temp stack space for the task. The task module with its ! $BLD command (ALPHA deck) 
must immediately follow the !$TCB card; otherwise the CONNECT subroutine will malfunction. The use of !$TCB 
commands is further discussed in Chapter 12 of this manual. 

INITIALIZATION 

In initialization, you have the option of allowing the Overlay Loader to do all the work (thus avoiding the problem 
of determining whether the Main program entry is really the initial entry), or you can use the CONNECT subroutine 
in an initialization routine. 

If the Overlay Loader Is to do the InltlaHzatlon, you must then specify a W], W2 on the l$TCB cards (see the !$TCB 
command In the Overlay Loader chapter In the RBM Reference Manual, and "How To Create Task Control Blocks" 
in this manual). 

If the Main program Is to perform an Initialization function, then only the Main program need have a w^, w^ field 
entry. 



Z 



!EOD 



X 



Task BETA 




!$LD BI, 1 



!$TCB ,,t3 



Task ALPHA 




!$LD BI, 1 



•TCB ,,t. 



^ 



y 



lEOD 

/ 



Z. 



Subroutines 



Main Program 




!$ROOT ti,,BI 



!$TCB w], W2 



lOLOAD 



y 



Figure 59. Overlay Loader Controls For Sample Real-Time FORTRAN System 
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Initialization 



You could use a mixture of these two approaches if desired. A Main program and one or more tasks might be 
initiated by the Loader. Then, at the occurrence of some specified set of conditions, other tasks could be con- 
nected to their respective interrupts. 

SUBROUTINE SHARING 

Caution must be exercised if subroutines could possibly be shared by two or more interrupts after activation. Where 
this condition exists, you must be able to ensure that a subroutine is either in the Public Library or that it uses only 
dynamic storage (directly or indirectly). 

PUBLIC LIBRARY FORTRAN ROUTINES 

Since all routines in the FORTRAN Library fulfill the requirements for conversion to a reentrant subprogram, it is 
possible to convert a FORTRAN subroutine into a Public Library routine. As previously stated, a routine to be con- 
verted must use M:RES, M:PUSH, MrPUSHC, or M:PUSHK for storage allocation, and the static temp stack must be 
empty and allocated at the end of the program. 

With these conditions fulfilled, the Overlay Loader can be used to convert a FORTRAN routine to a Public Library 
version. In general, the conversion involves altering the storage allocation calling sequence so that it requests 
dynamic temp and by stripping the static temp stack from the end of the program. The chapter "How To Write Reen- 
trant Subroutines In Assembly Language" in this Manual and the Overlay Loader chapter in the RBM Reference Man- 
ual give more specific details. 
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18. HOW TO DEBUG ASSEMBLY LANGUAGE PROGRAMS 



The mosf useful features of the RBM Debug package are conditional dumps and the capability to insert code. Both 
of these features require a region of memory that we will call the "Insertion block". 



HOW TO DEFINE AN INSERTION BLOCK 



The insertion block Is defined with the Debug command: 
/ D start, end 



and must be given before any code insertions or snapshots may be specified. The most convenient way to define the 
Insertion block limits is to initiate program execution with an !XED control command that will cause the message 

HDKEYIN 

to be output on the OC device after the program is loaded into core. At this point, you can type in the Insertion 
block definition, type in the conditional snapshots and/or code Insertions, and then begin execution. 

HOW TO INSERT SNAPSHOTS AND CODE 

The listing in Figure 60 Is an example of a background program using a conditional snapshot and two code insertions. 
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DATA 
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READ AUTB, WAIT* STD ERR RECOVERY 
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0009 
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DATA 
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INBUFF 


BUFFER ADDRESS 
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DATA 
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DATA 
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WRITE EBCDIC, WAIT# STD ERR RECBVeRY 
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DATA 
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DATA 
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DATA 
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003C 
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OOOC 
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E 
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END 


START 




* N8 ERROR 


LINES 
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•END 

















Figure 60. Example, Background Conditional Snapshot With Two Code Insertions 
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MAP 

aVERLAY TASK BA 9RQ.3F00 HLBC«503D CBAS.FOOO CSlZnOOOO U^lE^^aSFCS SECTvOOOS 
R89T eRG«5ooO LWA»5o3D LEN»003E TRA»5oOO SEV»0000 8VjLeAD«N8NE 
ERRSEV* 0000 
PNO MAP 
ET-000.27 
MeSSaGe WHeN DKeYIM is BUtPUT, TYPe in IC» F9LL9WE0 BY NeW LINe 

Pause set prstect switch t» »8Ff», interrupt, keyin is» 

XFO 
OKEYIN 

c 

<»0O0jK000 

S 5003/RA<J5I|I0/'ERR9R»/RR 

IB 5003* D01C#620*»RCPYIPL,'»C01* 5007 

IR 5006,'»0«S000 

B 

ET«000*5« 



Figure 60. Example, Background Conditional Snapshot With Two Code Insertions (cont. ) 

The example in Figure 60 reads one 80-character record from the OC device, outputs the same record on the OC 
device, and then terminates. 

The !$ROOT card causes the program to be loaded for execution at X'5000'. Since the beginning of background is 
at X'3F00' in the system used for this example, the region from X'SFOO' to X'SFFF' is used as dynamic temp space 
for the program. 

When the MDKEYIN message is output, the operator types in "C", w^hich causes Debug to read further commands 
from the Debug DI device. 

The S (snapshot) command tests for register A being equal to the value 0, following the call to M:READ. If A does 
not equal zero, the message 



ERROR 



is output on the Debug DO device, followed by a hexadecimal dump of the register contents. 

The IB (Insert Before) command inserts a test for an EOF condition (A=3) before the snapshot. The symbolic equiva- 
lent of the inserted code is 

CP =3 

BNC $+3 

B *$+! *$+! 

DATA STOP 

The IR (Insert Replace) command inserts an unconditional branch back to START, following the call to M:WRITE. 
The symbolic equivalent of the inserted code is 

B START 
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HOW TO DEBUG A FOREGROUND PROGRAM 

The use of Debug with a foreground program involves the use of a high-level interrupt for use by RBM while the 
foreground program is active. The background program example given previously in Figure 60 can be made to 
operate in the foreground as shown in Figure 61. 

The IROOT card shown in Figure 61 causes the program to be loaded so that the label START is at location X'340O' 
The start of the program is computed as 

TCB address - exioc (X'3300') + temp (X'E5') 

START = TCB address (X'33E5') + TCB size (X'lB') 

Since the default temp size is X'50', the !$ROOT command could also be 

!$ROOT ,+3395, GO 



to cause the label START to be on a convenient boundary. The TCB would still be at X'33E5' 
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Figure 61. Foreground Conditional Snapshot With Two Code Insertions 
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MAP 

OVERLAY TASK FS eR9«3500 HLSC«35A8 CBAS||3EEE CSIZ.QOOO UMEMvOg^fS SECT<0OO2 
Raer eRQ»3550 LWA»35A8 LeN«oo59 TRA«N9NE SEV'OOOO 9VjL©A0«NeNE 
ERRREV* 0000 
END MAP 
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Pause <eyin Fa#s 

Message when dkeyin is butput, type in ici reuewEO by new line 

XED 

DKEYIN 

C 

OjIIO 

03200«3^00 

S $PR0G4>3/RA<>iK0/«'ERRSRSRR 

IB •PRBQ*3, OOlC* 6204, RCPYlPL* *COl# •PR93+7 

IR «PR9Q*6«40««PR8a 

3 

C: *3550«7 



Figure 61. Foreground CondiHonal Snapshot With Two Code Insertions (cont. ) 

HOW TO USE $NAME AND ©NAME 

The Debug package provides two methods of referring to program locations by name rather than by hexadecimal 
value. Both methods involve the use of an arbitrary symbol of up to eight alphanumeric characters preceded by a 
$ or by an @ sign. Examples: 

$PROGRAM 

$SEG1 

@START 

@S 

REQUIREMENTS FOR $NAME 

1. The source program must include an IDNT statement. Example: 

ID NT 'PROGRAM' 

2. The iOLOAD command used to load the program must contain the character Das the fourth parameter. Example: 



A 



OLOAD 0,F,,D 



3. The Debug insertion block must be large enough to contain a blocking buffer for reading from the opera- 
tional label ID. The blocking buffer is allocated as the last K:BLOCK words of the insertion blocks, where 
K:BLOCK words of the insertion blocks have the value 180 or 512. This value is contained in location 
X'EE' in all RBM systems from Version DOO upward. If snapshots or insertions are to be made, the insertion 
block must be large enough to contain the blocking buffer and the additional space required for the inser- 
tions or snapshots. 

The example in Figure 62 shows how the $NAME feature can be used with a foreground program. 
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EOO 


OOJOl 09/22/71 PAGE I 


1 


REF MJReAD,MJWRITE/M»EXIT 


2 0000 C839 A 


START LOX PlNLlST READ 


3 0001 75 A 1 A 


RCPYI l#a FRBM 


4 0002 4C38 A 


B M J READ 8C 


S 0003 C838 A 


WRITE LOX "leUTLIST WRITE 


f, Q00<* 75A1 A 


RCPYI 1#8 8N 


7 OOOS 4C37 A 


B MJWRITE 8C 


8 0006 75A1 A 


ST9P RCPYI 1,8 TERMINATE 


9 0007 *C36 A 


B M;EX1T TASK 


10 0O08 3006 * 


INLIST DATA X»3006» READ AUTB, WAIT* STD ERR ReCBVeRY 


11 0009 D6C3 A 


Data 'bc» bpeRationaL label 


\? OOOA 0011 R 


DATA INBUFF BUFFER ADDRESS 


13 OOOB 0050 A 


DATA 80 BYTE C8UNT 


1* OOOC 3005 A 


9UTLIST DATA Xi3005» WRITE EBCDIC/ WAIT# STD ERR RECOVERY 


IB OCOO D6C3 A 


DATA »8C» 


16 OOOE 0010 R 


DATA 8UTBUFF 


17 OOOF 0050 A 


DATA 80 


18 OOlO fOOO A 


8UTBUFF DATA XiFqOO' OBUBLE SPACE F8RMAT C80E 8 NULL 


1"» OOll 


INBUFF RES HQ 


80 0000 R 


END START 


0039 0008 R 




003A 0000 E 




003B OOOC R 




0O3C 0000 C 




003D 0000 E 




« N8 ERRSR LINES 




• CRR9R severity; 




ET-000.10 




8L8AD 0,F 




•MS 




•TCB ♦llll**1805 


INTERRUPT 111« ARM S ENABLE 


•R89T ♦E5**3300jG8 




«ENO 




MAP 




SVERLAY TASK FS 8R6,3300 HU6C.343D CBASsSEEE CSIZpQOOO UMEMpQABo SECTiOOOZ 


R88T 8RQ»33C5 LMA«3430 LeN>oo59 TRAaN8NE SEV-QOOO 9V|L8A0-NeNE 


ERRSEV* OOOO 




E.NO MAP 




ETaOOOtia 




Pause keyjn fq*s 




MeSSaQe WHeN OKeYIN IS 8UTPUT, TYPe IN «Ci FBLLOWEO BY NEW LINE 


XEO 




DKEYTN 

C 

0<110 






D 3200<a300 




S 3«03/RA<>il<0/'ERR8Ri«RR 




IB 3403«001C#620*#BCPYIPL««C01*3*07 | 


IR 3*06«'»0«3400 
B 




Cj ♦33E5#7 


TRIGGER INTERRUPT 



Figure 62. Foreground Debug Example Using $NAME 
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REQUIREMENTS FOR (SNAME 

When it is desirable to be able to refer to locations within a program, the use of a Debug symbol table Is required. 
The symbol table may be assembled into the program or it may be constructed in an unused area of core with Debug 
Modify commands. Use of the @NAME facility allows you to write snapshots for subroutine entry or exit points, to 
simulate input values, etc, for programs being assembled and executed within the same job. 

The structure of the Debug symbol table is 



s 




S 


s 




S 


s 




^6 


s 




s 


Value 



Symbol name, left-justified and padded with blanks 
to a total of 8 characters. 



The location value to be used. 







Indicates end of table. 



The Debug G command is used to define the start of the symbol table, 
using @NAME with a background program. 



The listing in Figure 63 is an example of 



EOO 














00101 09/22/71 PaQE 1 


1 










def 


symtab 














REF 


m:reao#hiwrite/m 


iTERM 




0000 
0001 


E2E3 

C109 




SYMTAB 


TEXT 


•START t 






0002 


E3«0 














0003 


#040 














000* 


0010 






DATA 


START 






0005 

0006 
0007 

0008 


E6#0 
#0*0 
*0*0 

40*0 






TEXT 


• W » 






0009 


0013 






DATA 


WRITE 

» ST9P • 






OOOA 


E2E3 






TEXT 






OOOB 


D607 














OOOC 


*0*0 














0000 


4040 














OOOE 


0016 






DATA 


ST9P 






OOOF 


0000 






DATA 







10 


0010 


C839 




START 


LOX 


•INLISt 


Read 


11 


0011 


75AI 






RCPYI 


1*2 


FR8M 


t9 


0012 


4C38 






B 


MIREAO 


9C 


13 


0013 


C838 




WRITE 


LOX 


-eUTLIST 


WRITE 


1* 


001* 


75AI 






RCPYI 


1»Z 


ON 


15 


0015 


4C37 






8 


MiWRITE 


ec 


1* 


0016 


75 A 1 




ST8P 


RCPYI 


1«2 


TERMINATE 


17 


0017 


4C36 






B 


M J TERM 


PRB6RAM 


1« 


0018 


3006 




INUIST 


DATA 


X 130061 


READ AUT9# WAIT* STO ERR REC9VERY 


19 


0019 


06C3 






DATA 


•8C« 


OPERATIONAL LABEL 


20 


OOU 


0021 






Data 


INBUFF 


BUFFER ADDRESS 


21 


OOIB 


0050 






DATA 


80 


BYTE COUNT 


22 


ooic 


3005 




9UTLX8T 


DATA 


XI 3005 » 


WRITE EBCDIC, WAIT* STO ERR REC9vERY 


23 


0010 


D6C3 






DATA 


(8C< 




2* 


OOIE 


0020 


R 




DATA 


9UTBUFF 




2S 


OOlF 


0050 


A 




DATA 


80 





Figure 63. Background Debug Example Using @NAME 
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EOO 00101 09/22/71 PaQE 


2 


24 0020 FOOO A 9UTBUFF DATA XIFOOO' DBUBLe S^aCe ^BRMaT CoDE 5 NULL 




27 0021 INBUFF RES 40 




2« 0010 R END START 




00*9 0018 R 




004A 0000 E 




00*B OOIC R 




00*C 0000 E 




00*0 0000 E 




* NS ERROR LINES 




* CRRSR SEVERITVI 




ET»000.13 




9LBA0 




•ML 




«R»ST *1100«#6e 




•END 




MAP 




SVERLAY TASK BA 8RG.3F00 HLeC«50#D CBAS.FOOO CSIZ.OOOO UMEM«9Fe2 SECT«0002 




OEF MiFSAVE 0*7D 




OEF OJKEY 27AB 




DE^ OS Card 27ac 




OEF DiSNAP 27AD 




OEF MJSAVE 27A6 




OEF MJEXIT 27A7 




OEF MJI8EX 27AE 




OEF MtREAD 27B0 




OEF MjWRlTE 27Bt 




OEF M J CTRL 27B2 




OEF M:tERM 27B* 




OEF «i: DAT I ME 27B3 




OEF MIAB9RT 27B5 




OEF M J HEX IN 27B6 




OEF MIINHeX 27B7 




OEF MICKREST 27B8 




OEF MlLOAD 27A8 




OEF m:9PEN 27B9 




OEF MSCL9SE 27BA 




OEF MIDKeYS 27BB 




OEF m:WAIT 27BC 




OEF MjSESLO 27BD 




OEF M J DEFINE 27BE 




OEF M J ASSIGN 278F 




OEF MJ9PF1LE 27C0 




OEF M;PbP 27CI 




OEF M|RES 27C2 




OEF MjOYN 27C3 




OEF MiRSVP 27A9 




OEF MJ08W g7AA 




OEF MICeC 27aF 




R8ST 0RQ"5O0O LViiAti5G«D LEN-004E TRA«5010 SEV-OOOO SVtLeADvNBNE 




DEF SYMTAB I 8000 




ERRREV. 0000 




END MAP 




ET«000»20 




PAUSE SET PROTECT SWITCH T9 'OFF'* INTERRUPT* KEYiN »S« 




MESSAGE WHEN DKEYIN IS BUTPUT* TYPE IN »Cl eBLLBwED BY NEW tINE 




XED 




DKEYIN 




C 




D 40004 SOOO 




G5Q00 




8 8W/RA<>il>0/«tERRBR>«RR 




IB 8W,Do1Cj620**RCPYiPL#*COI*SST9P*1 




IR SSTBP«40«aSTART 
B 




ET»000»5o 




FIN 





Figure 63. Background Debug Example Using @NAME (cont. ) 
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19. HOW TO ASSIGN AND USE DEVICE OPERATIONAL LABELS 



Physical devices are normally assigned af SYSGEN to device file numbers (DFNs). However, at Installations v^here 
relatively large numbers of personnel submit jobs on a somev^hat irregular basis. It Is highly useful to permanently 
assign device mnemonic operational labels to hard-to-remember DFNs. This is particularly true when large numbers 
of Utility jobs are submitted, since the Utility processor works only with operational labels. 

For instance, a nonprofessional programmer would find it much easier to use 

/lASSIGN BO=M0 



Instead of the standard DFN assignment of 
/! ASSIGN BO=10 



for a temporary assignment of binary output to a magnetic tape unit. 

Or again, the nonprofessional programmer submitting a Utility job could assign (for Instance) 
/! ASSIGN U=CR 



Instead of a "normal" DFN assignment of 



lASSIGN UI-3 



to read in his input, with much less possibility of an incorrect assignment. 

When permanently assigning DFNs to operational labels at SYSGEN, the opiabels should convey as much mnemonic 
information as possible. The following list, however, is suggestive only: 

Typical Physical Suggested 

DFN Device Mnemonic Opiabel 

1 Keyboard/Printer KP 

2 Line Printer LP 

3 Card Reader CR 

4 Card Punch CP 

5 Paper Tope Reader PR 

6 Paper Tape Reader PP 

10 Magnetic Tape Unit MO 

In Magnetic Tape Unit n Mn 

The assignment of DFNs to device mnemonic operational labels takes place during the SYSGEN assignment of the 
background operational labels (see "BCKG, OP. LBL" output message in the SYSGEN Input Options and Parameters 
table in the System Generation chapter of the RBM Reference Manual). 
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Assuming that the card reader is assigned DFN3, the permanent SYS GEN assignments would appear as 

SI =3 

UI = 3 

CR = 3 
with corresponding device mnemonic operational labels for other DFN assignments. 
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20. HOW TO PATCH RBM 



RBM can be patched either temporarily or permanently through use of the RBM Hex Corrector. Whether the patch 
is temporary or permanent is determined by the manner in which the Hex Corrector Is activated. 

A temporary patch means that the copy of RBM located on the RAD Is not altered, and this Is achieved by activating 
the Hex corrector via a !HEX control command or an "H" operator key-In. 

A permanent patch means that the RAD copy of RBM jl altered, and therefore the changes will remain in effect for 
all future boots of the system from the RAD. Permanent changes are effected through activating the Hex Corrector 
by setting DATA switch 1 when RBM Is booted in. By using the two methods in conjunction, you can check 
out patches on a temporary basis and when satisfied that they are correct, make the patches permanent. 

When the Hex Corrector has been activated by either one of the two methods described above, it will read records 
from the CC operational label and write records on the DO operational label. The records read In are either bias 
or corrector records. 

Bias records have the form 



bbbb 
ID 



a 



[*Comments] 



bbbb is a hexadecimal number. 

PA represents the RBM Patch area defined at SYSGEN. 

XX is an REM overlay identifier (for example, 41 is the Hex Corrector), 

Corrector records have the form 



aaaa cccc_ cccc, . . . cccc.. . , cccc r*commentsl 
1 I n 



where 

aaaa is the hex location where the corrections will go. (If a bias card has been encountered, aaaa will be 

added to It to determine the location of the patches.) 

cccc. is the hex correction to be Inserted at the location aaaa + bias + I. The hex correction cccc; may also 

also be of the form Recce; which means the value to be stored Is ccccj + bias, or It may be of the form 
Pcccc; which means the value to be stored Is cccc; + bias of the RBM Patch area. 

An !EOD terminates the Hex Corrector's input. 
Figure 64 shows sample Input to the Hex Corrector. 
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t 



!EOD 

0030 4C01 POOOl *B PA+1 



+ID41 *HEX CORRECTOR 



0010 4C01 lOFF* *B TOFF 



0001 4C01 ROOlO *B PA+IO 



+IDPA *RBM PATCH AREA 



The first and lasf cells of the RBM Patch area should not be used for corrections, since the first contains the 
length of the Patch area and the last contains the number of temporary RBM overlay patches. Each temporary 
overlay patch takes three Patch area v/ords (taken from the top of the Patch area down). 



Figure 64. Hex Correction Input Example 
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21. HOW TO SAVE AND RESTORE AN RBM SYSTEM 



The RAD Editor can be used to save and restore an RBM system without the necessity of going through a complete 
SYSGEN. Two methods are available for saving the RBM system files: rebootable save and file save. 



HOW TO CREATE A REBOOTABLE SAVE TAPE 

The following control command sequence 



!#END 



!#SAVE 



IRADEDIT 



{REWIND BO 



! ASSIGN BO=T0 



! PAUSE MOUNT IFST SAVE TP ON UNIT 



IJOB 



will generate a rebootable save tape on magnetic tape that contains the entire RBM system. 

Note that the "TO" device operational label used on the ! ASSIGN command instead of a standard device file num- 
ber (DFN) is an option that must be defined at SYSGEN (see Chapter 19). 

The RBM areas contained on the rebootable save tape may be restored in their entirety by performing a bootstrap op- 
eration with the magnetic tape, or may be selectively restored via the RAD Editor ."^RESTORE command. 



BOOTING AN RBM SAVE TAPE 

When an RBM save tape is bootstrap loaded via the hardware load procedure, the message 



RESTORING VERSION XX OF mm/DD/yy HRMN 



is output on the keyboard/printer. 



XX is the version of the RBM system, 



mm/DD/yy HRMN is the date and time the save tape was created. 



If no parameter follows !"^SAVE, the RAD Editor will save all areas currently known to RBM except CP (Check- 
point) and BT (Background Temp). 
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As each new area is encountered on the save tape, the message 



RESTORING AR TO DN 



is output on the keyboard printer 
where 

AR is the area mnemonic. 

DN is the device number to contain the area. 

If an area is being restored to a disk pack, the first occurrence of such an area will cause the following message to 
be output: 



IDLE, RUN TO WRITE 



If it is permissible to write on the indicated device, move the COMPUTE switch to IDLE and then back to RUN. 
This measure is intended to prevent inadvertent destruction of information on disk packs. 

If an I/O error occurs, the program will output an appropriate message and retry the operation. If the error condi- 
tion persists, the operator may abort the restoration of the area currently being restored by pressing the Control 
Panel INTERRUPT switch. This will cause the program to skip to the next area on the tape. 

When all areas have been restored (or the logical end of tape is encountered), the program will unload the input 
tape and execute the RBM bootstrap. 

SELECTIVELY RESTORING AREAS FROM A REBOOTABLE SAVE TAPE 

The control command sequence in the example 



!#END 



!#RESTORE UP, UD, UL 



IRADEDIT 



IPRTCTD AREAS 



! PAUSE KEYIN SY, S IF RESTORING TO,; 



! ASSIGN BI=TO 



!JOB 



will restore the User Processor, User Data, and User Library areas from a magnetic tape that was generated as de- 
scribed previously. 

The RAD Editor restores the selected areas to their currently allocated regions, which must be on the same device as 
they were at the time of the save. However, the areas being restored need not be to the same physical region of 
the device. If the BOT of the area being restored is different from the BOT of the current allocation for that area, 
the restore will proceed normally and the area file directory will be updated to reflect the new file positions. If 
the area being restored contains nonzero data past the EOT of the current allocation, an EOT message will be out- 
put and the area will be truncated to fit the current allocation. In this case, the updated file directory may con- 
tain files that appear beyond the area EOT; these files should be deleted. 
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Note that selective restoration may not be used to restore the SP or SD areas. The bootstrap operation must be 
used if the SP or SD areas are to be restored. 

HOW TO SAVE RBM SYSTEM FILES 

If the RAD Editor !"^SAVE command is used with the keyword "FILE", the files indicated by the remainder of the 
parameters are saved on the BO device, which may be a magnetic tape, a paper tape punch, or a card punch. 

Each file is identified by its area mnemonic and file name, together with sufficient information to restore the file 
to the area from which it was saved. The example 



!#END 



FILE1,FILE2 



!#SAVE FILE, UP, UD, FILEl, FILE2, UL, Dl, ; 



IRADEDIT 



!JOB 



will cause the following files to be saved on the current BO device assignment: 
Area Files 



UP 




all 


UD 




FILE1,FILE2 


UL 




all 


Dl 




FILE1,FILE2 


RESTORING 


RBM 


SYSTEM FILES 



The RAD Editor !"^RESTORE command is used to restore files previously saved via a !*SAVE command. For example, 
if the commands 




were given with the output from the previous !*SAVE example being read from the BI device, the following files 
would be restored: 

Area Files 



UP 
UD 



All that existed at the time of the save would be added to current area contents. 
FILEl and FILE2 would be added to current area contents. 



In this method of restoring files, the file name is added to the area if it does not already exist; otherwise, the cur- 
rent content of the file is replaced by that from BI. 
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